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:
1 parent
c1d9494c11
commit
6bce301c55
10 files changed
+834
-2
No files matched your search
@@ -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
|
||||
Reference in new issue
Block a user