142 lines
6.5 KiB
Markdown
142 lines
6.5 KiB
Markdown
---
|
|
id: review-wave-7
|
|
name: Wave 7 review gate — the ops-vs-alkcall conformance gate
|
|
status: pending
|
|
depends_on: [ops-e2e-flows]
|
|
scope: narrow
|
|
risk: low
|
|
impact: phase
|
|
level: review
|
|
tags: [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`.
|
|
|
|
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
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |