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:
glm-5.3-flash committed 2026-10-11 23:48:23 +00:00
1 parent 79cf1f0220
commit 758ccfb359
7 files changed
+606 -2

No files matched your search

+99
View File
@@ -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