docs(tasks): decompose wave 3 — the sqlite kv engine, the durable delete window, the first SQL-backed column
Six tasks against the wave-2 contract surface as reviewed (no amendments from the gate): - engine-sqlite: the default kv engine — WAL + synchronous=NORMAL, prepared statements, the indexed size column probe (B5's row shape), has-as-EXISTS, virgin-store no-tables-yet tolerance, spawn_blocking discipline - engine-sqlite-window: the engine-state seam's window family only (ADR-012 §5's reduction — gc_window, stage/take; no pin rows, no sweep-lock body) - store-sqlite-construction: KvEngine::Sqlite slots in, the dual-tier/kv-only constructors with the constructor-tunable window delay (default 5 min), ensure_gc_schema at construction, the one-window-host posture - store-sweep-durable-window: the sweep's SQL-backed form — overdue rows execute with re-arbitration before/alongside marking, candidates stage at mark_end + window, counts exact relative to the schedule (ADR-012 §6.7); the inline form preserved verbatim - suite-column-sqlite: the first SQL-backed column, server-less — form-independent reference rows mirror directly; the sweep rows are schedule-relative (the recorded INV-4/5 mirror amendment) - review-wave-3: the engine-wave gate (engine-vs-contract conformance) Verification: dependency graph validated (all ids resolve, no cycles, topological order clean); docs-only change. Refs: docs/plans/implementation.md §Wave 3
This commit is contained in:
1 parent
79cf1f0220
commit
758ccfb359
7 files changed
+606
-2
No files matched your search
@@ -0,0 +1,99 @@
|
||||
---
|
||||
id: store-sweep-durable-window
|
||||
name: the sweep's durable-window form — staged candidates, next-sweep execution
|
||||
status: pending
|
||||
depends_on: [store-sqlite-construction]
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: phase
|
||||
level: implementation
|
||||
tags: [wave-3, store, gc, sweep]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Grow the sweep's **SQL-backed form** (ADR-008 §2; ADR-012 §5/§6.7)
|
||||
beside the inline form in `src/store.rs` — the first durable delete
|
||||
window, single-node:
|
||||
|
||||
- **The branch**: the sweep runs the durable form when the kv engine
|
||||
hosts the window (sqlite — the one-window-host posture); the inline
|
||||
form is preserved **verbatim** for non-SQL engines (mem/local — the
|
||||
wave-2 sweep tests stay green unchanged). The branch keys off the
|
||||
engine representation (the `KvEngine` match), never off a flag.
|
||||
- **The single-node posture is unchanged** (ADR-008 §2): pins, RAII
|
||||
guards, and the arbitration lock stay in-process (`GcHome`) — only
|
||||
the *persistence* of the delete window (the staged-candidate table)
|
||||
is engine rows.
|
||||
- **The durable form's protocol** (per sweep, under the lease):
|
||||
1. **Execute overdue** (before/alongside marking — ADR-012 §6.7):
|
||||
`window_take(now)` returns the overdue keys; each is
|
||||
**re-arbitrated at execution time** through the same
|
||||
`arbitrated_delete` path and deleted in batches. The protect-
|
||||
consult posture on this path is a recorded design point (the
|
||||
sweep's protect consult covers its execution phase — the same
|
||||
reasoning that keeps the inline form's candidates at
|
||||
`consult_protect = false`). A vanished candidate (deleted during
|
||||
the delay by a direct delete) settles into the cancelled count —
|
||||
the vanished-candidate accounting carries over.
|
||||
2. **Mark**: enumerate the pool, compute the live set, compute the
|
||||
candidate-dead set (unchanged).
|
||||
3. **Stage**: `window_stage(candidates)` at
|
||||
`visible_after = mark_end + window` — the constructor-tunable
|
||||
delay (ADR-008 §2; the store carries the value its constructor
|
||||
took).
|
||||
4. **Report**: `candidates_staged` = candidates staged this sweep;
|
||||
`deleted`/`cancelled_by_arbitration` = the executed overdue set.
|
||||
**Exact-count invariants are asserted relative to this schedule**
|
||||
(ADR-012 §6.7) — staged-this-sweep and executed-this-sweep are
|
||||
different sets (the delay separates them); the suite's sqlite
|
||||
column asserts the two-sweep shapes (`suite-column-sqlite`).
|
||||
- **Abort shapes unchanged**: `NoLivenessSources`/`ProtectFailed`/
|
||||
`SweeperLock` abort before anything is staged or executed (nothing
|
||||
deleted, `Ok(SweepReport)`); operational failures (engine I/O) are
|
||||
the `Err` half (ADR-012 §1).
|
||||
- **The sweep-vs-put race under the durable form**: a put landing
|
||||
during the window delay pins in-process (pin-before-publish); the
|
||||
execution-time re-arbitration sees the pin and cancels the candidate
|
||||
— the test-asserted property (a visible entry is never deleted while
|
||||
liveness protects it; an in-flight put is never deleted by a sweep
|
||||
started before it committed) holds **across the delay**, and is
|
||||
unit-tested in that form.
|
||||
- **Unit tests** in `store.rs`: two-sweep exact-count shapes (sweep 1
|
||||
stages N at delay 0 → sweep 2 executes exactly N — deleted +
|
||||
cancelled == N against the staged set); the race across the delay
|
||||
(put during the window survives; the unpinned twin deletes); the
|
||||
abort shapes on a sqlite store; the vanished-candidate form; the
|
||||
inline form untouched (the mem/local suites stay green).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The sweep branches on window hosting; the inline form's behavior
|
||||
and its wave-2 tests unchanged
|
||||
- [ ] Durable form: overdue rows execute with execution-time
|
||||
re-arbitration before/alongside marking; candidates stage at
|
||||
`visible_after = mark_end + window`
|
||||
- [ ] Report counts exact relative to the schedule (unit-tested
|
||||
two-sweep shapes); aborts delete nothing
|
||||
- [ ] The race property unit-tested across the delay (a put landing
|
||||
during the window survives the next sweep's execution)
|
||||
- [ ] The protect-consult posture on overdue execution recorded
|
||||
- [ ] `cargo test` (default) green; `cargo clippy --all-targets -- -D
|
||||
warnings` and `cargo fmt --check` green
|
||||
|
||||
## References
|
||||
|
||||
- src/store.rs (the sweep — `sweep`/`sweep_window`/`arbitrated_delete`)
|
||||
- docs/architecture/decisions/005-pooled-cas-and-gc-mechanism.md (§Sweep — the protocol)
|
||||
- docs/architecture/decisions/008-trait-size-probe-fleet-gc-and-large-engines.md §2 (the staged re-arbitrated delete; the delay)
|
||||
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §1 (abort-as-data), §5 (single-node posture unchanged), §6.7 (the executor is the next sweep)
|
||||
- docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §2 (the lease semantics)
|
||||
- src/gc.rs (`GcHome` arbitration; `EngineWindowState` the store core calls)
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
Reference in new issue
Block a user