---
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