Wave 4 decomposed: Postgres engine — 11 tasks (schema, open/opts, seam, forwarder, mechanisms, scheduler/outbox, integration, review gate); plan synced

2026-10-08 22:49:00 +00:00
1 parent ecb8211694
commit 4caea21098
@@ -0,0 +1,101 @@
+---
+id: pg-engine-integration
+name: Postgres engine — integration (full-surface wiring, suite adoption, crate docs)
+status: pending
+depends_on: [pg-engine-notify-listen, pg-engine-streams, pg-engine-queues, pg-engine-locks, pg-engine-scheduler-outbox]
+scope: moderate
+risk: medium
+impact: phase
+level: implementation
+tags: [wave-4, postgres-engine, integration]
+---
+
+## Description
+
+Close the wave's integration gaps once every mechanism is wired — the
+structural twin of wave 3's integration task (no lint-suppression
+removal on this side: the pg engine is greenfield, no `#![allow]`
+posture ever existed — the sweep below is the same discipline without
+that step):
+
+- **Full-surface sweep**: every `Store`/`TxHandle`/mechanism trait
+  method implemented (no `todo!`/`unimplemented!`/error-stub
+  remaining); the engine crate's lib re-exports its public surface
+  (`open`, `PgOpts`, the concrete store type) per the module-per-file
+  convention. Genuinely dead code must be **cut, not suppressed** —
+  clippy `-D warnings` green without allows.
+- **Contract-suite adoption** (the plan's "waves 3 and 4 adopt the
+  harness"): implement `StoreFactory` for the pg engine — **a fresh
+  schema per `open`** (the SQLite factory's fresh-temp-file
+  precedent; the POC's shared-server parallel-interference caveat is
+  answered by exactly this isolation — each property's rows live in
+  its own schema, so parallel property runs never observe one
+  another), idempotent teardown (`DROP SCHEMA … CASCADE`; safe
+  against an abandoned store per the factory contract's teardown
+  posture). Pin the factory's isolation/idempotence contract (the
+  SQLite factory's pin shape).
+  Wire the engine's backlog column — the rows this engine owns now,
+  running against the pg factory:
+  - The ADR-023-stamped rows (extent-clamp, duration-refusal,
+    `encode_payload` round-trip) — already written suite-side,
+    factory-parameterized; they run against pg by this task's
+    factory existing (verify, don't rewrite).
+  - **The pg arm of the engine-scoped rows**: `PayloadTooLarge`
+    produced (the pg rejection arm — oversized `notify`/`notify_tx`
+    rejected client-side with the limit in the variant; the row text
+    the SQLite integration task left for "wave 4's adoption"),
+    drop = rollback no-ghosts, in-tx read-your-own-writes,
+    enqueue-opts resolution, receiver close arms (the pg arm: stays
+    open across reconnects, closes at shutdown — the row's
+    engine-asymmetric legs may need the row split or parameterized
+    per the suite's convention; implementer's choice, documented).
+  - The SQLite-scoped rows (plain-path open §3, poll cadence §4)
+    simply don't run against pg — the SQLite integration task's
+    Notes already pinned that disposition.
+- **Crate docs**: the engine crate's lib-level doc comments state the
+  multi-host posture and the listener budget line (ADR-016,
+  deployment.md) — the identity statements this crate owns (the open
+  task drafted them; this task verifies they reflect the finished
+  engine).
+- **Gates**: full workspace build/test/clippy/fmt (the pg tests skip
+  cleanly server-less but must be green against the harness server);
+  coverage spot-check on the engine crate (no large uncovered regions
+  outside error arms — the wave-3 gate's bar).
+
+## Acceptance Criteria
+
+- [ ] No `todo!`/`unimplemented!`/error-stub in the engine crate;
+      full trait surface implemented; clippy `-D warnings` green
+      without allows
+- [ ] `StoreFactory` implemented for pg (fresh schema per `open`,
+      idempotent CASCADE teardown); the factory's
+      isolation/idempotence contract pinned
+- [ ] The backlog column runs green against the pg factory: the three
+      ADR-023 rows verified (not rewritten), the pg arm of the five
+      engine-scoped rows present + stamped
+- [ ] The `PayloadTooLarge` pg arm row present (the SQLite
+      integration task's deferred adoption discharged)
+- [ ] Crate lib docs carry the multi-host + listener-budget posture
+      statements, reflecting the finished engine
+- [ ] Workspace gates green: `cargo build`, `cargo test` (incl.
+      against the harness server), clippy `-D warnings`, fmt clean
+- [ ] Coverage spot-check: no large uncovered regions outside error
+      arms
+
+## References
+
+- docs/plans/implementation.md (Wave 4 section)
+- docs/architecture/core-contract.md (§Verification backlog)
+- docs/architecture/decisions/022-contract-suite-layout.md
+- docs/architecture/decisions/023-fourth-review-round.md (backlog additions)
+- docs/architecture/decisions/016-deployment-honesty.md §5
+- alkstore-sqlite/tests/contract_suite.rs (the factory precedent)
+- alkstore-contract-suite/src/properties.rs (the rows to run/adopt)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion