alkstore/tasks/review-wave-4.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-wave-4	Review gate — wave 4 (Postgres engine)	pending	pg-engine-integration	moderate	low	phase	review	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