docs(tasks): decompose wave 7 — the ops surface, the alkcall-backed op family behind the default-off feature
This commit is contained in:
glm-5.3-flash committed
1 parent
e84a874715
commit
c9829836b1
8 files changed
+852
-2
No files matched your search
@@ -0,0 +1,142 @@
|
||||
---
|
||||
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
|
||||
Reference in new issue
Block a user