user-engine/workplans/USER-WP-0016-durable-store-migration-and-conformance-harness.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id
USER-WP-0016	workplan	Durable Store Migration And Conformance Harness	netkingdom	user-engine	finished	codex	netkingdom	medium	16	2026-06-16	2026-06-16	USER-WP-0009 USER-WP-0015	91f9494a-7cc8-4e61-bec8-9440dfe0e63d

USER-WP-0016 - Durable Store Migration And Conformance Harness

Goal

Turn the durable-store follow-up from USER-WP-0009 into an executable adapter contract: ordered migrations, a Postgres bootstrap schema, and reusable conformance checks that future database-backed stores can run against the same behavior as the in-memory reference adapter.

Scope Direction

This slice should stay inside user-engine and avoid production infrastructure dependencies. It should define what a provider-backed adapter must satisfy without requiring a live Postgres service in the local unit test suite.

Non-Goals

• Do not add a production Postgres driver or connection lifecycle.
• Do not own platform provisioning, credentials, backups, restores, or provider observability.
• Do not require Docker, a cloud database, or network access for the standard test suite.

Tasks

id: USER-WP-0016-T1
status: done
priority: high
state_hub_task_id: "3783e912-76b5-4458-a8c5-a96bc8870e60"

Define an ordered migration manifest with the latest schema version and the logical store record types covered by user-engine.

id: USER-WP-0016-T2
status: done
priority: high
state_hub_task_id: "7d65e1fa-c7fb-4c83-9512-98296e6ccf4b"

Add a Postgres bootstrap SQL file that provider repositories can apply or translate when implementing the store boundary.

id: USER-WP-0016-T3
status: done
priority: high
state_hub_task_id: "c58db383-bfad-4f52-82d4-9d3c4558b1f2"

Add reusable store conformance helpers covering readiness, idempotent migration, core save/read methods, tenant and user queries, transaction rollback, outbox ordering, and redacted diagnostics.

id: USER-WP-0016-T4
status: done
priority: medium
state_hub_task_id: "71e51aa8-2a2b-463d-938b-0a1f1261c568"

Run the conformance helpers against InMemoryUserEngineStore as the reference implementation.

id: USER-WP-0016-T5
status: done
priority: medium
state_hub_task_id: "e8d7cece-605d-4bb3-b0c6-b03fb908e7c0"

Document how future Postgres/provider adapters should consume the manifest, SQL bootstrap file, and conformance harness.

Acceptance Criteria

• LATEST_SCHEMA_VERSION and the local adapter schema version come from the same manifest.
• The Postgres bootstrap file contains durable tables for schema versions, logical records, audit records, and outbox events.
• A future adapter can import one conformance helper and run it with its own store factory.
• Standard local tests prove the harness against the in-memory store.
• Diagnostics expose counts only and do not leak raw factor or profile values.

Expected Outputs

• user_engine.migrations manifest.
• migrations/postgres/0001_user_engine_store.sql.
• user_engine.testing.store_conformance helper.
• Store conformance tests.
• Updated durable-store documentation.

Implementation Notes

Implemented on 2026-06-16:

• Added an ordered migration manifest with logical record and diagnostic count keys.
• Added a provider-facing Postgres bootstrap SQL file for the generic record, audit, and outbox storage contract.
• Added reusable store conformance helpers and reference tests for the in-memory adapter.
• Aligned local schema readiness with LATEST_SCHEMA_VERSION.
• Documented the harness in the durable-store consumer requirements and contracts docs.