alkblobs/tasks/review-wave-7.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
review-wave-7	Wave 7 review gate — the ops-vs-alkcall conformance gate	completed	ops-e2e-flows	narrow	low	phase	review	wave-7 review

Description

The wave-7 review gate (docs/plans/implementation.md §Review gates: "ops-vs-alkcall conformance (the machinery ridden, not re-invented); ACL mapping vs OQ-09's closed-by-default; the pin token contract vs ADR-010 §4/ADR-012 §2; no backend side-door"), before wave 8 decomposes. The gate reads the implementation against the pinned ADR text line by line (the wave-1..6 gates' method) — the documents, not memory.

Gate checks:

• ops-vs-alkcall conformance — the machinery ridden, not re-invented: the JSON control plane rides OperationSpec + JSON Schema validation + typed error schemas (alkcall ADR-016); the binary data plane rides the channel_open marker + establishment (alkcall ADR-047/049) with the Sub/Sink handler kinds (ADR-021/ 046); ACL is alkcall's AccessControl at op entry (ADR-011) under the ADR-017 privilege model; producer/consumer vocabulary throughout; no parallel framing, validation, or authorization invented anywhere in the module.
• ACL mapping vs OQ-09's closed-by-default: namespace-as-resource (resource_type: "blob-namespace", the resource_id_path selecting the payload's namespace field); the read action on fetch/stat/have, the write action on put; unlisted namespaces deny by default (no ACL entry ⇒ no read, no write — verified by test, not by reading the code); delete not namespace-gated at all — internal authority context only (alkcall ADR-017: internal switches context, never skips ACL).
• The pin token contract vs ADR-010 §4/ADR-012 §2: the token is the pin (no second pin state); the blobs/put response {token, digest} with both fields always present; the have renewal form (one digest + token; verify-mapping → the crate- internal pin_renew; expired/foreign → present: false, no renewal); the token's validity domain = the minting node (foreign tokens refused present: false, not an error); the mapping's process lifetime (outlives the handler); the guard-custody split (fleet: the guard drops at response completion — the row's expiry is the liveness signal; non-fleet: the registry holds the guard — nothing expires); the TTL/3 renewal cadence is embedder composition (ADR-013 §1) — no in-crate renewal worker.
• No backend side-door (ADR-001 §4): the ops module's store access enumerated — the public facade plus the crate-internal renewal seam only; no Backend touch, no engine types, no ops-internal path around the store facade; the e2e audit's enumeration re-verified against the code.
• The fanout seam vs POC #3 finding A3: one reader, store arm + subscriber arms; late joiners degrade to a verified post-commit get (identical bytes under CAS); the slow-subscriber drop-and-late-join policy is ops-layer; the producer-side design point consistent with the A3 text.
• The base crate stays lean: the ops feature default-off; the alkcall + serde + CSPRNG deps ride the gate; the default build's dependency tree unchanged (convention 8; ADR-013 §4's table).
• Code-smell / hygiene sweep (the gate's standing hygiene block):
  • cargo doc --no-deps zero warnings (the PGLO-1 class — public-module doc links resolving to crate-internal items — de-link rather than export).
  • The #![allow(dead_code)] scope notes match their remaining scope — the ops module's notes audited; pin_check's wave-6 "deliberately unconsumed" note updated to its landed state.
  • Stale forward references updated — every "wave 7" note in the module docs reads the landed state.
  • Family conventions: no inline 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, no blocking I/O on the async path.
  • Task-description correctness: each wave-7 task's Summary matches what actually landed (the gate reads the diffs against the task texts, not the Notes' claims alone).
• Gates green: cargo test (default), cargo test --features ops, cargo test --all-features (the fleet rows live at acceptance), the pure builds (cargo check --no-default-features --features postgres / --features "postgres,pg-lo"), cargo clippy --all-targets -- -D warnings across the feature variants (default, ops, all-features, the pg-pure builds), cargo fmt --check, cargo doc --no-deps. (The engine-less builds — --no-default-features alone, with or without ops — have never compiled, identical E0004s independent of the feature; a zero-engine store is not a supported configuration — ADR-014 §4's verified non-finding. Not a gate row.)
• No stub ships from this crate (ADR-014 §4): nothing in src/ or the landed tests contains a stub-shaped not_implemented surface or asserts stub behavior; every registered op is capable of serving (put was held unregistered, not stubbed, until the ADR-014 §3 gate cleared — alkcall 0.9.0, 2026-10-14 — whereupon the put task registered it).

Findings are fixed inline where cheap, or recorded as wave-8 amendments where they shape the next decomposition (the fuzzing wave's target inventory reads this wave's surfaces — a payload-shape finding lands beside it). The gate's completion is what unblocks wave 8'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-8 amendments with owners
• All gates re-run green after any fixes — including cargo doc --no-deps explicitly (the PGLO-1 class)
• Wave 8 decomposition unblocked (recorded in this task's Summary)

References

• docs/plans/implementation.md (§Wave 7, §Review gates — the ops-vs-alkcall conformance gate)
• docs/architecture/ops-surface.md (the op family, the ACL mapping, the hand-over contract)
• docs/architecture/decisions/001-substrate-posture-and-ops-placement.md §2/§3/§4
• docs/architecture/decisions/006-verification-posture-and-transfer-encoding.md
• docs/architecture/decisions/008-trait-size-probe-fleet-gc-and-large-engines.md §2/§3
• docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md §4
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §2
• docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §1/§4
• docs/architecture/open-questions.md OQ-09
• docs/research/poc-largeblob-findings.md finding A3
• tasks/review-wave-6.md (the gate method; the W6-3 note this gate audits closed)
• tasks/ops-foundation.md, tasks/ops-call-harness.md, tasks/ops-json-ops.md, tasks/ops-fetch.md, tasks/ops-put.md, tasks/ops-e2e-flows.md (the wave's tasks)

Notes

Gate completed 2026-10-14, the wave-1..6 method: every gate check read against the pinned text (ops-surface.md; ADR-001 §2/§3/§4, ADR-006, ADR-008 §2/§3, ADR-010 §4, ADR-012 §2/§6, ADR-013 §1/§4, OQ-09, POC #3 finding A3, ADR-014; alkcall 0.9.0's ADR-016/017/021/ 046/047/049 and registry/spec.rs), then verified against the landed diffs. The operator's task-hash log matched git log exactly: ops-foundation 6feaa2a, ops-call-harness bc6da37, ops-json-ops 5144b6a, ops-fetch d927da2, ops-put be54f08, ops-e2e-flows c88d921 (with the ADR-014 docs + alkcall-0.9 bump commits between the fetch and put tasks).

Gate checks, each verdict:

• ops-vs-alkcall conformance — the machinery ridden, not re-invented — conformant. The JSON plane is OperationSpec + JSON Schema (input/output schemas per op, INVALID_INPUT fires at the registry before any handler) + typed ErrorDefinitions (ADR-016's shape); the data plane is the channel_open marker (channels/blobs/sub / channels/blobs/pub on alk/blobs — the standard name-derives-ALPN shape, no explicit channel_open_alpn) with the awaited establishment and the Sub/Pub handler kinds (ADR-021/046/047/049; put rides amendment 4's marked-pub machinery through register_pub_openable, ack-in-result). ACL is AccessControl + resource_id_path at op entry under ADR-017's model; producer/consumer vocabulary; no framing, validation, or authorization re-implemented anywhere in the module (the handlers' post-schema ingress is ingress, not validation). No stub ships: not_implemented/todo!/unimplemented! absent from src/ and the landed tests; put was held unregistered until the ADR-014 §3 gate (alkcall 0.9.0) cleared, whereupon the put task registered it.
• ACL mapping vs OQ-09 — conformant, verified by test (the harness's closed-by-default rows + the ACL matrix e2e): namespace = resource (resource_type: "blob-namespace", resource_id_path: "$.namespace"), the read action on stat/have/fetch, the write action on put; an unlisted namespace denies read AND write on the wire with a grant present elsewhere; ungranted identities denied at the call-plane gate. delete: Visibility::Internal, AccessControl::default() with no resource mapping (not namespace-gated), external discovery NOT_FOUND (ADR-017's visibility discipline), the internal path proven through composition under the declared composition authority.
• The pin token contract vs ADR-010 §4/ADR-012 §2 — conformant: the token is the pin (no second pin state); {token, digest} with both fields required by the response schema; the have renewal form (arity enforced at the schema's if/then and the handler's INVALID_RENEWAL_FORM; the verify-the-mapping-then-renew probe — registry lookup, one-token-one-row digest check, the store core's ops_pin_check classification, the never-resurrect ops_pin_renew; expired/foreign/mismatched/unknown all present: false, never an error); the validity domain = the minting node (per-process registry; the foreign-token refusal is symmetric, fleet-tested both directions); the mapping's process lifetime; the guard-custody split (fleet: mapping only, the guard's drop at response completion is the handler's act, row-expiry the liveness signal — live-tested with the gc_pins instrument, pin_count 0 at response; non-fleet: the registry holds the guard, nothing expires, conversion at the embedder's confirm); the TTL/3 cadence nowhere in-crate (no renewal worker exists — the e2e tests play the embedder's cadence role explicitly per ADR-013 §1).
• No backend side-door (ADR-001 §4) — conformant, re-verified against the code: the harness's structural audit enumerates every non-test store access and asserts the set equals the public facade verbs plus the facade's crate-internal pin/fleet access (gc, fleet — the ADR-010 §4 "crosses the seam by construction" access, pub(crate)) plus exactly the crate-internal renewal seam (ops_pin_check/ops_pin_renew, the W6-3 named consumer, store core-owned, zero public-API widening); forbidden-name assertions cover Backend and every engine type/crate path. The audit's task-text wording labeled fleet/gc "public facade verbs" — corrected inline (W7-3 below; the enumeration itself was accurate).
• The fanout seam vs POC #3 finding A3 — conformant: one read of the put's stream (the tee hands each chunk once per arm), the store arm + bounded subscriber arms, the late-joiner degrade to the verified get (subscribe → None, channel end, tap-time-set with no prefix), the drop-and-late-join policy ops-layer (per-broadcast Stall/Drop), and the producer-side design point decided and recorded against the A3 text (fetches never produce read-side broadcasts — the put's stream reader is the canonical producer).
• The base crate stays lean — conformant: ops default-off pulling alkcall/serde/serde_json/getrandom; cargo tree (default features) contains none of them.
• Hygiene sweep — findings fixed inline (below): the fleet TTL row's racy stop assertion (W7-1), the stale forward references (W7-2), the task-text hygiene (W7-3). cargo doc --no-deps zero warnings on the default and ops builds; the all-features doc build sits at the pre-existing private-link baseline (35 warnings, the recorded PGLO-1 residue — count identical before and after this gate's edits). The #![allow(dead_code)] scope notes audited and updated to their landed consumers: gc.rs's pin_check clause reads its wave-7 state (W6-3's note closed), the convert/ pin_count clause now reads the confirm verb as the ops build's non-test consumer, pg_lo.rs's orphan-recovery note reads the landed ops module (which consumes none of it), ops.rs's fanout section reads its landed producer/consumer wiring, store.rs's two "wave 7's wiring" notes read landed. Family conventions hold: no unwrap/expect outside tests, thiserror, tokio-only async, the one-module re-export shape, no blocking I/O on the async path (the fanout registry's arms are cloned out under the lock and driven outside it).
• Gates green (post-fixes; tests live against pglo-poc :15432 unless noted): cargo test 73/19/3 ok (default); cargo test --features ops 112/19/3 ok; cargo test --all-features 271/125/4 ok live; cargo test --no-default-features --features postgres (pg-pure, no ops) green; --no-default-features --features "postgres,pg-lo" 140 lib green; the pure-build checks green; clippy --all-targets -- -D warnings green on default, ops, and all-features; fmt green; doc counts above. The engine-less builds remain the recorded non-finding (not a gate row).

Findings fixed inline:

• W7-1 — the fleet TTL row's no-leaked-renewal assertion raced an in-flight write (fixed). fleet_ttl_the_pin_guards _ ttl_third_renewal_moves_the_rows_expiry asserted strict expiry equality across a single post-drop read; a renewal write in flight at the guard's drop (legal — the test's own doc comment admits one tick there) landed after the read and moved the row once, flaking under load. Pre-existing wave-6 test-harness race, not machinery or a wave-7 regression: it reproduces with ops compiled out (--no-default-features --features postgres) and it failed for two earlier wave-7 tasks likewise; no leaked duty exists (the expiry freezes after the one movement). Fixed test-side: the row's freeze is now asserted across two settled reads taken beyond the expiry horizon, with the expiry-never-moves-backwards guard for the one in-flight landing — leaked-duties detection is unchanged (a leak keeps moving the row through both reads). Suite re-run green across the shapes recorded above.
• W7-2 — stale forward references (fixed). ops.rs's fanout section ("the producer wiring lands with ops-put"), store.rs's two "wave 7's wiring" notes, pg_lo.rs's "the ops/maintenance surface is wave 7+" note, and gc.rs's muddled "the conversion's in-sweep consumer being wave 7's liveness edit flow" trailing clause all rewrote to landed readings.
• W7-3 — task-text hygiene (fixed). ops-fetch and ops-e2e-flows carried unchecked acceptance boxes whose work was verified and Summarized; ops-put's Notes/Summary carried unfilled placeholder lines above filled content; the audit's fleet/gc access mislabeled "public facade verbs" — all corrected.

Wave-8 amendments: none. No payload-shape finding surfaced: the fuzzing wave's target inventory proceeds per plan (key encoding + the ops JSON specs + the binary channel framing).

Summary

Completed 2026-10-14 (wave 7's review gate). The gate read the landed ops implementation against the pinned text line by line and found it conformant on every check: the alkcall machinery ridden end to end (OperationSpec + JSON Schema + typed error schemas; the channel_open marker, establishment, and Sub/Pub machinery incl. alkcall 0.9's amendment-4 marked-pub surface; AccessControl at op entry), the ACL mapping closed-by-default verified by test, delete internal-authority-only and not namespace-gated, the pin-token contract vs ADR-010 §4/ADR-012 §2 exact (the token is the pin; the renewal form's three answers; the validity domain; the custody split; no in-crate renewal worker), the no-side-door enumeration re-verified against the code (the facade + the pin/fleet access + exactly the renewal seam), and the fanout seam against the A3 text with the producer-side design point recorded. Three findings fixed inline: the pre-existing fleet-TTL race assertion (settled across two reads; flake confirmed pre-wave-7 and with ops compiled out), the stale "wave 7" forward references across five module docs, and the task-text hygiene (unchecked-but-done boxes, leftover placeholders, the audit's fleet/gc wording). No wave-8 amendments — no payload-shape finding. All gates re-run green after the fixes (test suites live against the harness server, the clippy variants, the pg-pure checks, fmt, and cargo doc --no-deps zero-warnings on the default and ops builds at the recorded all-features baseline). The operator's task-hash log matched git log. Wave 8 (fuzzing) decomposition is unblocked.