feat(engines): the mem contract-reference engine — first real engine (wave 2)

- src/mem.rs: MemBackend implements Backend (seven methods + put_staged,
  name "mem") over Arc<parking_lot::Mutex<BTreeMap<..>>>; CAS
  first-writer-wins puts, materializing MemCursor body, degenerate
  in-memory MemStaging whose commit publishes via the same CAS clause
  and self-discards on failure; discard leaves zero residue.
- CAS re-put is dedup for both put forms; reads are no-ops on the
  virgin store; delete carries Missing; size is metadata-only.
- Eight in-module tests mirror the wave-1 double's assertions: method
  contract, list well-formedness, cursor body read contract + ADR-006
  range digest, empty-entry round-trip, staged happy path, and both
  hygiene forms (fail_commit test hook stands in for media failure).
- backend.rs: clamped promoted pub(crate) — the shared EOF-clamping
  arithmetic both mem cursor bodies compose (no per-engine duplicate).

Verification: cargo test --features mem (33+7 green); cargo test
(default) green; clippy --all-features --all-targets -D warnings green;
fmt --check green.
This commit is contained in:
glm-5.3-flash committed 2026-10-11 21:56:29 +00:00
1 parent 6bce301c55
commit 0b43ea1449
3 files changed
+527 -6

No files matched your search

+44 -3
View File
@@ -1,7 +1,7 @@
---
id: engine-mem
name: mem kv engine — the contract-reference engine
status: pending
status: completed
depends_on: []
scope: narrow
risk: low
@@ -69,8 +69,49 @@ this task ships the engine and its in-module unit tests only.
## Notes
> To be filled by implementation agent
- `backend.rs`'s `clamped` (already documented as "the shared EOF-clamping
arithmetic of the cursor contract") was promoted `pub(crate)` so both
mem cursor bodies compose it — no per-engine duplicate of the clamp.
- `MemBackend`/`MemStaging` are `pub(crate)` (the Backend trait is
crate-internal per ADR-003's visibility design point); the module
carries `#![allow(dead_code)]` mirroring `backend.rs`'s seam-scope
pattern, which shrinks when dispatch names the mem engine.
- parking_lot's `Mutex` does not poison, so the
`unwrap_or_else(|e| e.into_inner())` posture has nothing to apply to —
plain short-held locks (AGENTS convention 3).
- mem's `commit` cannot fail in normal operation (no media). The wave-1
double's `fail_commit` knob is carried as a `#[cfg(test)]` field on the
backend/staging pair so the failure form's self-discard hygiene is
exercised against the real engine; it stands in for the media-failure
injection later engines need (the conformance suite's fault-hook story
is `suite-column-mem`'s concern).
- Not fleet-valid (ADR-011 §4): no `gc` engine-state implementation —
confirmed SQL-engine-only in src/gc.rs.
## Summary
> To be filled on completion
Implemented the `mem` contract-reference engine (feature `mem`) in
`src/mem.rs`: `MemBackend` implements `Backend` completely (name `mem`;
`has`/`get`/`put`/`put_staged`/`delete`/`list`/`size`) over an
`Arc<parking_lot::Mutex<BTreeMap<Vec<u8], Vec<u8>>>>`. `put` is CAS
first-writer-wins (`entry().or_insert_with()`); `get` hands out
`MemCursor`, the materializing kv body (whole value, EOF-clamped reads,
`len()` from the stored value); `put_staged` hands out `MemStaging`, the
degenerate in-memory stage — `append` extends, `commit` publishes via the
same CAS clause (`std::mem::take` before the lock; losing the race is
dedup, never a failure) and self-discards on failure, `discard` drops the
buffer with zero residue. Reads are no-ops on the virgin store; `delete`
carries `Missing`; `size` is metadata-only.
Eight in-module unit tests mirror the wave-1 double's assertions against
the real engine: the method contract (virgin no-ops, CAS re-put, Missing
discipline, size exactness), list completeness/well-formedness, the
materialized cursor body's read contract (EOF clamping, zero-length, and
the ADR-006 read_range digest), the empty-entry round-trip, the staged
happy path (verification pass over the staged whole through the read
seam, then both re-put forms are dedup no-ops), and both hygiene forms
(discard → zero residue; injected commit failure → self-discard).
Verification: `cargo test --features mem` green (33 unit + 7 integration),
`cargo test` (default) green, `cargo clippy --all-features --all-targets
-- -D warnings` green, `cargo fmt --check` green.