---
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
---

# 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
```

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

```task
id: USER-WP-0019-T2
status: done
priority: high
```

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

```task
id: USER-WP-0019-T3
status: done
priority: high
```

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

```task
id: USER-WP-0019-T4
status: done
priority: medium
```

Add live checks for migration readiness and deterministic upsert uniqueness.

```task
id: USER-WP-0019-T5
status: done
priority: medium
```

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.