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

+80
View File
@@ -0,0 +1,80 @@
---
id: suite-column-local
name: Conformance suite — the local column and the dispatch-coverage shape
status: pending
depends_on: [suite-column-mem]
scope: moderate
risk: medium
impact: phase
level: implementation
tags: [wave-2, suite, local, dispatch]
---
## Description
Grow the **local column** — the suite's first dual-tier column, run
against the `kv = mem` + `large = local` factory: the
**dispatch-coverage test shape** ADR-012 §6.3 names (both tiers
load-bearing). Rows mirror the mem column's set (INV-7: every engine's
rows mirror the reference column), extended with the dual-tier and
local-specific properties.
- **The factory**: fresh, isolated temp-root dual-tier store per call
(`kv = mem` + `large = local`), idempotent teardown (temp dir
removal); never skips.
- **Mirrored rows** (the mem column's set, against the dual-tier
store):
- **INV-1 round-trips**: both tiers, both put paths — the content
matrix crosses the threshold so both tiers' bodies are exercised
(sub-threshold kv rows; over-threshold local stage-commit rows).
- **INV-3 stage hygiene**: exact counts **on disk** — zero stage
files after every failure form, exactly one committed entry per
success, over both put paths (the real stage form, not the
degenerate kv stage).
- **INV-4 sweep safety**: exact-count sweep outcomes over the
dual-tier pool (candidates from both tiers; abort shapes; the
sweep-vs-pinned-put race).
- **INV-2 dedup, INV-5 list-through-sweep, INV-6 stat** mirrored.
- **Dispatch rows** (the coverage shape's reason to exist):
- Routing is a pure function of length: same content ⇒ same tier
across mixed put paths and re-puts; no content ever migrates.
- **Fall-through** (ADR-012 §6.1): a kv-tier miss queries the large
tier — `get`/`stat`/`has`/`read_range` each served from the large
tier when the kv tier misses; both-tier miss shapes per op.
- Threshold boundary values (at/below/above the default; a
constructor-tuned threshold re-routes deterministically).
- **Local-specific rows**: pread range reads over committed files
(mid-file slices, EOF clamping); virgin-store no-ops on a fresh root
(empty `list`, absent reads); `size` as a stat (never a content
load).
- Every row ADR-stamped per the convention, tracing to the backlog.
## Acceptance Criteria
- [ ] The dual-tier `kv = mem` + `large = local` factory green with
isolation + idempotent teardown
- [ ] The local column green: mem's row set mirrored (INV-1/2/3/4/5/6)
plus dispatch rows (pure-function routing, fall-through per op,
threshold boundaries) and local-specific rows (pread ranges,
virgin-store no-ops, stat-as-stat)
- [ ] Stage-hygiene exact counts asserted on disk (the real stage form)
- [ ] Every row ADR-stamped and traceable to the backlog
- [ ] `cargo test` green (local is ungated — the column runs in the
default build); clippy/fmt gates green
## References
- tests/conformance/README.md + backlog.rs (the conventions; INV first-column plan)
- docs/architecture/backends-and-dispatch.md (§Constructor modes — the dispatch-coverage shape; §Size-threshold dispatch)
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.1/§6.3
- docs/architecture/decisions/003-backend-contract-and-dispatch.md (§Dispatch policy)
- docs/architecture/store-api.md (§Invariants)
- docs/research/poc-largeblob-findings.md (findings A2/A5)
## Notes
> To be filled by implementation agent
## Summary
> To be filled on completion