alkblobs/tasks/review-wave-5.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
review-wave-5	Wave 5 review gate — the pg-lo engine vs the contract	pending	suite-column-pg-lo	narrow	low	phase	review	wave-5 review

Description

The wave-5 review gate — the engine-wave review shape (docs/plans/implementation.md §Review gates: "engine-vs-contract conformance"), before wave 6 decomposes. The gate reads the implementation against the pinned ADR text line by line (the wave-1/2/3/4 gates' method).

Gate checks:

• Engine-vs-contract conformance: the suite column green against dockerized postgres (server-less runs skip cleanly — a skip never substitutes for acceptance); the engine-state clause families contract-tested per the applicability row (ADR-012 §5's pg-lo row — the window family only, conditional per the one-window-host rule); virgin-store semantics; the size metadata-only discipline (the companion-row probe never loads LO content).
• The engine shape vs ADR-009 §1–§4: the companion table is the contract authority (list/size/has/CAS all table-level); pg_largeobject never read for addressing; put = one tx with the 512 KiB knee as a named constant (the C2 citation); the staged put's held-tx body with both hygiene forms exact-count tested; gets ride descriptorless lo_get(oid, off, len) windows (the C4 posture — the held-descriptor fallback named as not-shipped, never coded); the 64-bit-variants discipline (the C7 int4 trap not inherited); delete = one tx under table-level arbitration; transactional LO creation (zero crash orphans structurally — the C6 reading).
• The posture deltas vs ADR-009 §5/§6: carried as requirements, not hedges — catalog space never returned (the VACUUM FULL operator line + rel-size monitoring named in the module doc); autovacuum inherited, keep it on; the orphan-recovery sweep present for the legacy/bypass class (scope-noted, contract-tested with a planted orphan); the cached-get capacity facts named honestly.
• The one-window-host rule vs ADR-012 §5: the store-core completion — ensure_gc_schema follows the host rule at construction (dormancy on dual-SQL: the consolidation shape's pg-lo schema carries no gc_window; the pg-lo host on kv=mem); the sweep form branch runs the durable form on the pg-lo host for kv=mem + large=pg-lo and keys off the engine representation, never a flag; no fleet state anywhere in pg-lo (nothing of EngineFleetState); the fleet joint-put contribution's API shape explicitly deferred to wave 6 (recorded, not silently absent).
• The consolidation constructor vs ADR-009/011/012: the fleet-valid engine set completed; the implicitly-fleet: false posture recorded verbatim (wave 6's declaration slots in without reshaping); the connection-settings design point (two DSN+opts pairs; cross-instance valid non-fleet) recorded.
• Async/blocking discipline: tokio-postgres natively async — no spawn_blocking seam; no blocking I/O on the async path; the pool is the concurrency posture; no unwrap/expect outside tests.
• Named design points audited as resolved (each recorded in its task's Notes): the schema name + the consolidation shape's schema sharing; the shared-helper home (quote_identifier, 42P01 discriminant, pg_err, timestamp helpers) + the PgOpts gate question; the 512 KiB aggregation shape; the LO isolation + janitor shape (amendment A2 verified — zero schema AND zero pg_largeobject residue on the shared db); the sub-enum slotting for the large cursor/staging bodies; the connection-settings shape; the dormancy wiring; the orphan sweep's scope note.
• Family conventions: no comments in code (doc comments on public API fine), thiserror, tokio-only async, no unwrap/expect outside tests, naming, one-module-per-file re-export shape, the #![allow(dead_code)] scope notes matching their remaining scope.
• Gates green: cargo test (default), cargo test --features pg-lo (server-less: skipping), cargo test --features "pg-lo,mem", cargo test --all-features (against the server), the pg-lo pure builds (cargo check --no-default-features --features "pg-lo,mem" and --features "postgres,pg-lo" — the literal kv-less --features pg-lo config is not a gate: with no kv engine the facade's KvEngine/KvCursor go empty, E0004; see store-pg-lo-construction), cargo clippy --all-targets -- -D warnings (default + the pg-lo variants + --all-features), cargo fmt --check, cargo doc --no-deps.

Findings are fixed inline where cheap, or recorded as wave-6 amendments where they shape the next decomposition (the fleet mechanism's joint-tx driver already carries amendment A1; any pg-lo contribution-shape finding lands beside it). The gate's completion is what unblocks wave 6's decomposition.

Acceptance Criteria

• Every gate check above read and verified against the cited ADR text (not from memory of it)
• Named design points each decided, recorded, and consistent with the specs
• Findings fixed inline or recorded as wave-6 amendments with owners
• All gates re-run green after any fixes
• Wave 6 decomposition unblocked (recorded in this task's Summary)

References

• docs/plans/implementation.md (§Wave 5, §Review gates — engine wave reviews)
• docs/architecture/decisions/009-pg-lo-large-tier-engine.md
• docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md §1/§2
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §3/§4/§5/§6.7
• docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §4
• docs/architecture/store-api.md
• docs/research/poc-pglo-findings.md (the evidence base the engine claims)
• tasks/review-wave-4.md (the gate method; the structural twin's gate)

Notes

To be filled by implementation agent

Summary

To be filled on completion