generated from coulomb/repo-seed
108 lines
2.7 KiB
Markdown
108 lines
2.7 KiB
Markdown
---
|
|
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.
|