test: add provider postgres conformance

workplans/USER-WP-0019-provider-backed-postgres-conformance.md

@@ -0,0 +1,107 @@
+---
+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.