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

+76
View File
@@ -0,0 +1,76 @@
---
id: engine-mem
name: mem kv engine — the contract-reference engine
status: pending
depends_on: []
scope: narrow
risk: low
impact: component
level: implementation
tags: [wave-2, engines, mem]
---
## Description
Implement the `mem` kv-tier engine (feature `mem`; ADR-011 §2): a
`BTreeMap`-shaped ephemeral implementation of the kv tier's contract —
the first real engine, and the **contract-reference engine**: every
other engine's conformance rows mirror its column (store-api.md
invariant 7), so its bodies are the shapes the suite holds the rest to.
- **Backend impl** (`src/mem.rs`, behind `#[cfg(feature = "mem")]`)
against the wave-1 trait (`src/backend.rs`): the seven methods plus
`put_staged`, opaque byte keys/values, `name() -> "mem"`.
- `put` — CAS first-writer-wins (`entry().or_insert()`); a re-put of
an existing key is a no-op, never an overwrite.
- `get` — `None` on absence (never `Error::Missing`); the cursor body
is the **materialized family** (the whole value; `len()` from the
stored value).
- `put_staged` — the **degenerate in-memory stage** (ADR-010 §1: kv
bodies stage in memory and commit through the whole-value row
write); `append` extends the buffer, `commit` publishes via the
same CAS clause and self-discards on failure, `discard` drops the
buffer with zero residue.
- `delete` — `Err(Error::Missing)` when absent; `list` — complete and
well-formed (the map's keys); `size` — trivially metadata-only (the
stored value's length, no content fetch semantics to violate).
- Virgin-store reads are no-ops (an empty map is the virgin store).
- **Locking posture**: `parking_lot` for the short-held map lock
(AGENTS convention 3; `unwrap_or_else(|e| e.into_inner())` on
poisoning). No blocking I/O exists here.
- **Unit tests** in-module: the method contract (virgin-store no-ops,
CAS re-put, Missing discipline, size exactness), the staged-put happy
path and both hygiene forms (discard → zero residue; commit failure →
self-discard) — mirroring the wave-1 test-double's assertions, now
against the real engine.
The conformance column itself is `suite-column-mem` (separate task);
this task ships the engine and its in-module unit tests only.
## Acceptance Criteria
- [ ] `src/mem.rs` implements `Backend` completely (seven methods +
`put_staged`) behind feature `mem`, with the materialized cursor
body and the degenerate staging body
- [ ] CAS first-writer-wins on both put forms; re-put never overwrites
- [ ] Stage hygiene holds in both forms (discard → zero residue;
failed commit → self-discard), unit-tested
- [ ] Virgin-store reads are no-ops; `delete`/absent-key discipline per
the trait contract; `size` metadata-only
- [ ] `cargo test --features mem` green; `cargo clippy --all-features
--all-targets -- -D warnings` and `cargo fmt --check` green
## References
- docs/architecture/backends-and-dispatch.md (§kv tier — mem engine)
- docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md §2
- docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md §1
- src/backend.rs (the trait + seam contracts this implements)
## Notes
> To be filled by implementation agent
## Summary
> To be filled on completion