user-engine/workplans/USER-WP-0018-postgres-store-adapter.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-0018	workplan	Postgres Store Adapter	netkingdom	user-engine	finished	codex	netkingdom	medium	18	2026-06-16	2026-06-16	USER-WP-0016 USER-WP-0017	192a3a0c-81af-4004-a466-bf670fa99212

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

id: USER-WP-0018-T1
status: done
priority: high
state_hub_task_id: "b1beac60-bc8f-4d00-9387-aecb5c721755"

Add a Postgres adapter that implements the UserEngineStore protocol using the generic record, audit, and outbox tables.

id: USER-WP-0018-T2
status: done
priority: high
state_hub_task_id: "794796a0-0851-44c1-a27a-18e037295cb7"

Wire the adapter to StoreRecord serialization and deterministic record keys.

id: USER-WP-0018-T3
status: done
priority: high
state_hub_task_id: "160909a7-f626-4afc-97e2-151eedc4f255"

Support schema readiness, migration execution, transactions, audit reads, pending outbox reads, and adapter-neutral record counts.

id: USER-WP-0018-T4
status: done
priority: medium
state_hub_task_id: "4eeb3043-28a3-46d0-b7da-563686e9e28b"

Add a fake Postgres connection that runs the shared conformance harness without requiring production infrastructure.

id: USER-WP-0018-T5
status: done
priority: medium
state_hub_task_id: "58a6d45d-7f27-477e-9ddf-0d734086db21"

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.