docs(tasks): decompose wave 2 — mem + local engines, facade, in-process GC, first suite columns

Nine tasks against the wave-1 contract surface as reviewed (no
amendments from the gate):

- engine-mem / engine-local (parallel, dependency-free): the two
  engines; local owns the stage-hygiene exact-count tests and the
  Drop-cancellation story the wave-1 review recorded
- store-construction: the Store type, constructor modes, size-threshold
  dispatch; binds the conformance factory's Store associated type
- store-read-paths ∥ gc-protocol: read ops with the ADR-012 §6.1
  fall-through rule; the ADR-005 in-process protocol (pins, liveness,
  delete windows, abort-as-data, GcRefuse with the full protection set)
- store-put-paths: the two put paths behind one signature, ADR-003's
  three numbered rules, pin-before-publish, Batch, kv-only rejection
- suite-column-mem → suite-column-local: the reference column, then the
  dual-tier dispatch-coverage shape mirroring it
- review-wave-2: the gate (facade/dispatch/GC vs ADR-003/005/012)

Verification: dependency graph validated (all ids resolve, no cycles,
topological order clean); docs-only change.

Refs: docs/plans/implementation.md §Wave 2
This commit is contained in:
glm-5.3-flash committed 2026-10-11 21:39:28 +00:00
1 parent c1d9494c11
commit 6bce301c55
10 files changed
+834 -2

No files matched your search

+93
View File
@@ -0,0 +1,93 @@
---
id: review-wave-2
name: Wave 2 review gate — facade, dispatch, GC, and the first columns
status: pending
depends_on: [suite-column-local]
scope: narrow
risk: low
impact: phase
level: review
tags: [wave-2, review]
---
## Description
The wave-2 review gate, before wave 3 decomposes. Wave 2 made the
store work end-to-end dependency-free; the gate reads the
implementation against the pinned ADR text line by line (the wave-1
gate's method).
Gate checks:
- **Facade + dispatch + GC vs ADR-003/005/012**:
- the **three numbered unknown-length rules** (ADR-003 §Dispatch
policy) each read against their tests — mid-stream flush with no
restart requirement; verification over the eventual stored artifact
as a whole (buffer form and staged-bytes form); stream error leaves
no entry and no stage file;
- the **delete-window ordering invariants** (ADR-005 §Sweep):
pin-before-publish on both put paths and both tiers; arbitration
under the pin/liveness lock at delete time; the test-asserted
property (a visible entry is never deleted while liveness protects
it; an in-flight put is never deleted by a sweep started before it
committed);
- **abort-as-data** (ADR-012 §1): `sweep()` returns
`Ok(SweepReport)` on every abort; `GcRefuse` is the direct-delete
refusal only; the full protection set per ADR-012 §6.4;
- dispatch as a pure function of length (no migration); fall-through
general rule per ADR-012 §6.1; constructor modes per ADR-011 §4 /
ADR-012 §6.2/§6.3; kv-only put-time rejection.
- **Stage-hygiene exact-count tests**: present and exact on both
engines (mem's degenerate stage; local's real stage form incl. the
Drop-cancellation story per the wave-1 review's observation).
- **The suite's first columns green on mem + local**: rows
ADR-stamped, traceable to the backlog, the factory binding recorded
(factory.rs + README if corrected).
- **The dispatch-coverage shape exercised**: the `kv = mem` +
`large = local` column's dispatch rows (pure-function routing,
fall-through, threshold boundaries).
- **Named design points audited as resolved** (each recorded in its
task's Notes): engine representation (enum vs generic); the public
stream type; list return shape; verification-on-get posture;
liveness-source shape; Pin registry back-reference + lock
granularity; put stream parameter shape; len-mismatch error.
- **Family conventions**: no comments in code (doc comments on public
API fine), thiserror, tokio-only async, `spawn_blocking` for blocking
file work, no unwrap/expect outside tests, naming, module structure.
- **Gates green**: `cargo test`, `cargo test --features mem`, `cargo
test --all-features`, `cargo clippy --all-targets -- -D warnings`,
`cargo clippy --all-features --all-targets -- -D warnings`, `cargo
fmt --check`.
Findings are fixed inline where cheap, or recorded as wave-3
amendments where they shape the next decomposition. The gate's
completion is what unblocks wave 3'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-3 amendments with
owners
- [ ] All gates re-run green after any fixes
- [ ] Wave 3 decomposition unblocked (recorded in this task's Summary)
## References
- docs/plans/implementation.md (§Wave 2, §Review gates)
- docs/architecture/decisions/003-backend-contract-and-dispatch.md
- docs/architecture/decisions/005-pooled-cas-and-gc-mechanism.md
- docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md
- docs/architecture/store-api.md
- tasks/review-wave-1.md (the gate method; the observations wave 2 owned)
## Notes
> To be filled by implementation agent
## Summary
> To be filled on completion