feat: add postgres user engine store

workplans/USER-WP-0018-postgres-store-adapter.md

@@ -0,0 +1,107 @@
+---
+id: USER-WP-0018
+type: workplan
+title: "Postgres Store Adapter"
+domain: netkingdom
+repo: user-engine
+status: finished
+owner: codex
+topic_slug: netkingdom
+planning_priority: medium
+planning_order: 18
+created: "2026-06-16"
+updated: "2026-06-16"
+depends_on:
+  - USER-WP-0016
+  - USER-WP-0017
+---
+
+# USER-WP-0018 - Postgres Store Adapter
+
+## Goal
+
+Add a dependency-free Postgres store adapter behind `UserEngineStore` that uses
+the migration and serialization contracts from USER-WP-0016 and USER-WP-0017.
+
+## Scope Direction
+
+The adapter should accept a provider-supplied DB-API or psycopg-like connection
+and avoid owning credentials, pooling, deployment, backups, or platform
+observability.
+
+## Non-Goals
+
+- Do not vendor or require a Postgres driver in the core package.
+- Do not add Docker or live database requirements to the unit test suite.
+- Do not implement outbox claim/ack/retry or provider restore validation yet.
+
+## Tasks
+
+```task
+id: USER-WP-0018-T1
+status: done
+priority: high
+```
+
+Add a Postgres adapter that implements the `UserEngineStore` protocol using the
+generic record, audit, and outbox tables.
+
+```task
+id: USER-WP-0018-T2
+status: done
+priority: high
+```
+
+Wire the adapter to `StoreRecord` serialization and deterministic record keys.
+
+```task
+id: USER-WP-0018-T3
+status: done
+priority: high
+```
+
+Support schema readiness, migration execution, transactions, audit reads,
+pending outbox reads, and adapter-neutral record counts.
+
+```task
+id: USER-WP-0018-T4
+status: done
+priority: medium
+```
+
+Add a fake Postgres connection that runs the shared conformance harness without
+requiring production infrastructure.
+
+```task
+id: USER-WP-0018-T5
+status: done
+priority: medium
+```
+
+Document the provider boundary and remaining provider-backed conformance work.
+
+## Acceptance Criteria
+
+- The adapter has no hard runtime dependency on a specific Postgres driver.
+- The adapter passes the same store conformance harness as the in-memory store.
+- Migration readiness uses the shared latest schema version.
+- Record counts stay redacted and adapter-neutral.
+- Docs explain that provider repositories still own live-driver, lock, restore,
+  and outbox claiming validation.
+
+## Expected Outputs
+
+- `user_engine.adapters.postgres.PostgresUserEngineStore`.
+- Fake Postgres adapter tests.
+- Durable-store documentation updates.
+
+## Implementation Notes
+
+Implemented on 2026-06-16:
+
+- Added `PostgresUserEngineStore` using provider-supplied DB-API/psycopg-like
+  connections.
+- Reused `StoreRecord` serialization for all generic record writes and reads.
+- Added transaction, migration, readiness, audit, outbox, and record count
+  support.
+- Added fake connection tests that run the shared store conformance harness.