---
id: USER-WP-0016
type: workplan
title: "Durable Store Migration And Conformance Harness"
domain: communication
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: medium
planning_order: 16
created: "2026-06-16"
updated: "2026-06-16"
depends_on:
  - USER-WP-0009
  - USER-WP-0015
state_hub_workstream_id: "d5e04359-3ac2-4993-9e75-f5a282ef9c80"
---

# 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

```task
id: USER-WP-0016-T1
status: done
priority: high
state_hub_task_id: "fdb1bf47-17e6-4bdb-b822-1713217b81cf"
```

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

```task
id: USER-WP-0016-T2
status: done
priority: high
state_hub_task_id: "e2cd55ee-0779-4df1-80e7-62070c134a1b"
```

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

```task
id: USER-WP-0016-T3
status: done
priority: high
state_hub_task_id: "da8e9530-2a30-4c79-9a65-6f00a184b69d"
```

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

```task
id: USER-WP-0016-T4
status: done
priority: medium
state_hub_task_id: "b4bee55f-3e65-4c27-b2f0-accad0899d13"
```

Run the conformance helpers against `InMemoryUserEngineStore` as the reference
implementation.

```task
id: USER-WP-0016-T5
status: done
priority: medium
state_hub_task_id: "382ff39a-e081-49ea-9039-5dddfa03c587"
```

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.