alkblobs/tasks/store-sqlite-construction.md at 758ccfb359a724984fdc6a707fdbdf0727efa7e6

0 Fork 0

Files

T

glm-5.3-flash 758ccfb359 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

2026-10-11 23:48:23 +00:00

4.5 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level, tags

name

status

depends_on

scope

risk

impact

level

Description

Slot sqlite into the facade's engine representation — the slotting-in pattern src/store.rs's module doc pinned ("adding an enum variant and a named constructor is slotting in"):

KvEngine::Sqlite variant behind #[cfg(feature = "sqlite")] + the dispatch arms (put/get/has/size/delete/list). The kv cursor dispatch (AnyCursor's kv arm) carries the sqlite materializing body — the kv-arm shape over multiple kv engines (a KvCursor sub-enum vs per-engine variants) is a recorded design point. The #[allow(unused_variables)] empty-set scaffolding on the KvEngine methods shrinks (the kv set is no longer empty in default builds); backend.rs's #![allow(dead_code)] scope note about "the kv engines' whole-value put before wave 3" is updated to the landed state.
Named constructors, feature-gated on sqlite (default-on — the default build constructs them):
- dual-tier kv = sqlite + large = local — the default-build production shape; fallible (file I/O: opening/creating the database, creating the local root). Size-threshold dispatch at the constructor-tunable threshold as in the mem+local shape.
- kv-only(sqlite) — no large tier; threshold is the put-time rejection point (ADR-012 §6.2; the rejection machinery is the put seam's, already landed — only the constructor slots in).
- Both take the delete-window delay parameter (ADR-008 §2: the delete window's delay, default 5 min, constructor-tunable per deployment — a named shipped-default constant; Duration). This is the durable window's cadence knob the sweep's SQL-backed form consumes (store-sweep-durable-window); 0 is a legal degenerate tuning (execute-on-next-sweep — the test tuning). The mem/local constructors are unchanged: the inline form has no delay in effect.
ensure_gc_schema at construction — the store-core call (engine-neutral; sqlite's body creates gc_window only). A construction failure is Err(Error::Io) per the fallible-constructor pattern dual_tier_mem_local set.
The one-window-host rule's store-core posture (ADR-012 §5): the durable window hosts on the kv engine when it is SQL-backed — sqlite hosts. Recorded (code shape or doc note) so wave 5's pg-lo dormancy (the dual-SQL instance stages on the kv engine only) slots in without reshaping.
Constructor unit tests: the modes construct and introspect correctly (mode()/threshold()), ensure_gc_schema ran (the window table exists in the fresh database), the window-delay default is the pinned constant, kv-only rejection wiring unchanged, the dual-tier shape round-trips end-to-end (a smoke put/get through both tiers).

Acceptance Criteria

KvEngine::Sqlite slots in; all six kv ops dispatch; the kv cursor body dispatches (design point recorded)
dual_tier_sqlite_local + kv_only_sqlite constructors exist behind feature sqlite, take threshold + window delay, fallible where I/O is fallible
ensure_gc_schema runs at construction; the window-delay shipped default is 5 min (pinned constant) and constructor-tunable; 0 legal
The one-window-host posture recorded (sqlite hosts when the kv engine is SQL-backed)
The stale empty-set scaffolding/allow notes updated to the landed state
cargo test (default) green — the default build constructs and exercises sqlite stores; cargo clippy --all-targets -- -D warnings and cargo fmt --check green

References

src/store.rs (the engine-representation design point; the constructor modes; the slotting-in pattern)
docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md §4 (modes)
docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.3 (dual-tier shapes), §5 (the one-window-host rule)
docs/architecture/decisions/008-trait-size-probe-fleet-gc-and-large-engines.md §2 (the window delay, default 5 min)
docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §4 (the feature graph)

Notes

To be filled by implementation agent

Summary

To be filled on completion

4.5 KiB Raw Blame History