---
id: USER-WP-0019
type: workplan
title: "Provider Backed Postgres Conformance"
domain: netkingdom
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: medium
planning_order: 19
created: "2026-06-16"
updated: "2026-06-16"
depends_on:
  - USER-WP-0018
state_hub_workstream_id: "40dbb193-1cbc-49b2-a08e-044f504c25e6"
---

# USER-WP-0019 - Provider Backed Postgres Conformance

## Goal

Add opt-in live Postgres conformance tests for `PostgresUserEngineStore` so
provider repositories can prove the adapter against a real database without
making ordinary user-engine tests require infrastructure.

## Scope Direction

The suite should be skipped unless an explicit test DSN and destructive reset
acknowledgement are supplied. It should cover migration readiness, the shared
store conformance harness, uniqueness/upsert behavior, rollback semantics, and
record-count diagnostics against a real provider connection.

## Non-Goals

- Do not add a mandatory Postgres driver dependency.
- Do not run live database tests by default.
- Do not implement outbox claim/ack/retry or restore validation yet.

## Tasks

```task
id: USER-WP-0019-T1
status: done
priority: high
state_hub_task_id: "425f0c51-4333-4f63-8397-ddc0bfe8a428"
```

Add env-gated live Postgres connection helpers that support `psycopg` or
`psycopg2` when installed.

```task
id: USER-WP-0019-T2
status: done
priority: high
state_hub_task_id: "f180d009-097d-45b9-aa1f-586f219f7916"
```

Require an explicit destructive reset acknowledgement before cleaning
`user_engine_*` provider test tables.

```task
id: USER-WP-0019-T3
status: done
priority: high
state_hub_task_id: "e2bbf3bd-04a2-4344-a252-330f2a190a0c"
```

Run the shared store conformance harness against a live provider connection
when configured.

```task
id: USER-WP-0019-T4
status: done
priority: medium
state_hub_task_id: "f3b781d0-3a46-4bab-a2c0-f4eb14d70ca9"
```

Add live checks for migration readiness and deterministic upsert uniqueness.

```task
id: USER-WP-0019-T5
status: done
priority: medium
state_hub_task_id: "33591917-3099-415f-8d9b-70c5273cf3b3"
```

Document provider setup, skip behavior, and remaining live conformance gaps.

## Acceptance Criteria

- Standard `make test` skips live Postgres tests unless env vars are present.
- Live tests fail closed if a DSN is supplied without reset acknowledgement.
- Provider cleanup only touches `user_engine_*` tables created by the bootstrap.
- The live suite can use either `psycopg` or `psycopg2` if available.
- Documentation names the required env vars and remaining follow-up work.

## Expected Outputs

- `user_engine.testing.postgres_provider` helper.
- Env-gated provider-backed tests.
- Durable-store documentation updates.

## Implementation Notes

Implemented on 2026-06-16:

- Added optional provider connection and reset helpers for live Postgres tests.
- Added env-gated tests for migration readiness, shared conformance, and
  deterministic upsert uniqueness.
- Hardened adapter readiness before migration when provider tables do not yet
  exist.
- Kept the default unit suite dependency-free and infrastructure-free.