94 lines
4.0 KiB
Markdown
94 lines
4.0 KiB
Markdown
---
|
|
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 |