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:
1 parent
6bce301c55
commit
0b43ea1449
3 files changed
+527
-6
No files matched your search
+44
-3
@@ -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.
|
||||
Reference in new issue
Block a user