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

tasks/review-wave-4.md

@@ -0,0 +1,94 @@
+---
+id: review-wave-4
+name: Review gate — wave 4 (Postgres engine)
+status: pending
+depends_on: [pg-engine-integration]
+scope: moderate
+risk: low
+impact: phase
+level: review
+tags: [wave-4, review]
+---
+
+## Description
+
+Review the Postgres engine before wave 5 decomposes. Primary lens per
+the plan's review gates: **engine-vs-contract conformance** — the same
+discipline as the wave-3 gate, now against the second engine, with
+the pg-specific machinery added. Wave 5 (the contract suite) pins
+*cross-engine equivalence*; this gate checks the pg implementation
+against the pinned contract text line by line.
+
+Check:
+
+- **Contract conformance**: every trait method's behavior against
+  core-contract.md's per-mechanism text — validation at entry points
+  (auto-commit AND tx paths), error arms (`Database`-only receivers,
+  `Codec` at payload seams, `LeadershipLost` vs clean stop), value
+  shapes (`Job`/`StreamEvent` field-for-field), the no-work-is-a-value
+  vocabulary (`None`/`false`/empty-`Vec` where pinned, never errors).
+- **ADR-023 follow-through**: extent guards at trait-impl entry
+  (claims + all four stream reads); duration guards on both lock call
+  sites; `encode_payload` consumed fallibly at every call site.
+- **ADR-016 §5**: the 8000-byte check is client-side, typed, before
+  any round trip, on both `notify` and `notify_tx`; the limit constant
+  has one owner.
+- **Forwarder integrity** (the pg engine's own high-risk machinery —
+  the analogue of the wave-3 gate's seam-integrity lens): the two
+  POC-pinned deadlock pitfalls structurally excluded (poll loop
+  before first query; `Client` alive for the listener's lifetime);
+  reconnect backoff + re-LISTEN from the live channel set; the
+  synthetic reconnect-wake on the reserved string broadcast to every
+  subscriber; lag surfaced, not silent; receiver close semantics
+  exactly the pg arm (open across reconnects, close at shutdown
+  only, terminal, never reopens).
+- **Seam integrity**: drop = rollback under panic; failed
+  COMMIT/ROLLBACK arms discard (not re-pool) the object — pool
+  accounting exact under error paths (deployment.md's ADR-021 note);
+  ops-after-consume fail closed; no `spawn_blocking` anywhere (the
+  natively-async posture — a stray bridge would be a finding).
+- **Backoff curve + boundary math**: the engine-side formulas match
+  ADR-010 §3's pinned range/cap and ADR-009 §4's boundary guarantee
+  exactly (wave 5 pins cross-engine equivalence; this gate checks
+  this implementation against the text).
+- **Schema posture**: one engine-owned schema; payload columns
+  `bytea` (exact bytes — no JSONB normalization); no per-queue
+  tables; bootstrap idempotent.
+- **Backlog column**: the engine's suite rows present, stamped, green
+  against the pg factory; the `PayloadTooLarge` pg arm row present.
+- **Family standards**: no panics, no unwrap/expect outside tests, no
+  inline comments (doc comments fine), module-per-file.
+- **Gates**: full workspace build/test/clippy/fmt; the pg suite green
+  against the harness server.
+
+## Acceptance Criteria
+
+- [ ] Contract conformance spot-checked against the spec text (not
+      just the tests)
+- [ ] ADR-023's numeric-domain + typed-encoding follow-through
+      verified at their sites
+- [ ] Forwarder + seam integrity verified (code-read, not
+      test-name-trust)
+- [ ] Backoff curve + scheduler boundary math match the pinned ADR
+      text
+- [ ] Backlog column present, stamped, green against the pg factory
+- [ ] All gates green (incl. against the harness server)
+- [ ] Findings recorded; wave 5 decomposition may proceed
+
+## References
+
+- docs/plans/implementation.md (Review gates)
+- docs/architecture/core-contract.md
+- docs/architecture/engine-postgres.md
+- docs/architecture/decisions/004-postgres-driver.md
+- docs/architecture/decisions/016-deployment-honesty.md §5
+- docs/architecture/decisions/023-fourth-review-round.md
+- tasks/review-wave-3.md (the gate discipline's precedent)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion