alkblobs/tasks/review-wave-5.md

---
id: review-wave-5
name: Wave 5 review gate — the pg-lo engine vs the contract
status: pending
depends_on: [suite-column-pg-lo]
scope: narrow
risk: low
impact: phase
level: review
tags: [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