---
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
state_hub_workstream_id: "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

```task
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.

```task
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.

```task
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.

```task
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.

```task
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.