generated from coulomb/repo-seed
128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
---
|
|
id: USER-WP-0016
|
|
type: workplan
|
|
title: "Durable Store Migration And Conformance Harness"
|
|
domain: netkingdom
|
|
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: "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
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|