feat: add durable store conformance harness

docs/contracts.md

@@ -231,6 +231,21 @@ adapter or provider concerns outside the domain service.
 
 ## Migration Contract
 
-The isolated store exposes `SCHEMA_VERSION = 0001_initial` and a `migrate`
-hook. Database-backed stores must expose equivalent readiness semantics before
-they are accepted by platform adapters.
+`user_engine.migrations` exposes the ordered durable-store manifest,
+`LATEST_SCHEMA_VERSION`, logical record types, and adapter-neutral diagnostic
+count keys. The isolated store's `SCHEMA_VERSION` is derived from that manifest
+and its `migrate` hook must be idempotent. Database-backed stores must expose
+equivalent readiness semantics before they are accepted by platform adapters.
+
+Provider-backed Postgres adapters can use
+`migrations/postgres/0001_user_engine_store.sql` as the bootstrap contract or
+translate it into their own migration framework while preserving schema-version
+tracking, logical record uniqueness, audit durability, and pending-outbox
+reads.
+
+Future adapters should run
+`user_engine.testing.assert_user_engine_store_conformance(testcase, factory)`
+with a factory that returns a fresh store. The harness covers readiness,
+idempotent migration, core save/read/query behavior, transaction rollback,
+outbox ordering, and diagnostics that expose counts without raw factor or
+profile values.

docs/development.md

@@ -13,6 +13,7 @@ src/user_engine/
   adapters/    local standalone adapters and deterministic test doubles
   domain/      transport- and persistence-neutral domain schemas
   errors.py    typed service exceptions for callers and future transports
+  migrations.py ordered durable-store migration manifest
   ports.py     adapter protocols for identity, authorization, events, audit,
                membership export, application bindings, and secrets
   service.py   headless service API for the isolated MVP
@@ -50,8 +51,11 @@ The initial headless API is `UserEngineService`. It exposes health,
 readiness, `me`, user/account lifecycle, identity linking, application
 registration, catalog publication, profile writes, effective profile
 resolution, projections, audit inspection, and outbox inspection. The first
-store is `InMemoryUserEngineStore`, which carries an explicit schema version
-and migration hook so later database-backed stores have a contract to match.
+store is `InMemoryUserEngineStore`, which carries a schema version from
+`user_engine.migrations` and a migration hook so later database-backed stores
+have a contract to match. Future store adapters should run
+`user_engine.testing.assert_user_engine_store_conformance` with their own
+factory before being wired into service tests.
 
 ## Tenant Surface
 

docs/postgres-durable-store-consumer-requirements.md

@@ -282,10 +282,16 @@ The first consumer-side follow-up is complete: `UserEngineStore` defines the
 adapter boundary and the in-memory store acts as the reference implementation
 for service-level behavior.
 
+USER-WP-0016 adds the next consumer-side slice: `user_engine.migrations`
+declares the ordered migration manifest and latest schema version,
+`migrations/postgres/0001_user_engine_store.sql` defines a provider-facing
+bootstrap schema, and `user_engine.testing.store_conformance` exposes a
+reusable harness that future adapters can run with their own store factory.
+The standard local suite runs that harness against `InMemoryUserEngineStore`.
+
 Likely future follow-up work should be:
 
 - Add a Postgres adapter behind the existing store boundary.
-- Add migration files for user-engine tables.
 - Add provider-backed conformance tests for locking, uniqueness races,
   migration readiness, outbox claiming, redacted diagnostics, and restore
   validation.