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

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on
USER-WP-0019	workplan	Provider Backed Postgres Conformance	netkingdom	user-engine	finished	codex	netkingdom	medium	19	2026-06-16	2026-06-16	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

id: USER-WP-0019-T1
status: done
priority: high

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

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

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

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

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

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

Add live checks for migration readiness and deterministic upsert uniqueness.

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.