feat(store): the sqlite constructor wiring — the default-build store shapes

- KvEngine::Sqlite slots in; all six kv ops dispatch; the kv cursor
  body dispatches through a new KvCursor sub-enum behind AnyCursor's
  one kv arm (the kv-arm-over-multiple-kv-engines design point,
  recorded)
- dual_tier_sqlite_local (kv = sqlite + large = local, the
  default-build production shape) and kv_only_sqlite constructors —
  both feature-gated on sqlite (default-on), both taking the
  threshold and the delete-window delay, fallible where I/O is
  fallible (Err(Error::Io) per the dual_tier_mem_local pattern)
- ensure_gc_schema runs at construction via the engine-neutral
  KvEngine call (sqlite's body creates gc_window only); the
  window-delay shipped default is the pinned
  DEFAULT_DELETE_WINDOW_DELAY (5 min, ADR-008 §2), constructor-
  tunable, Duration::ZERO legal — the store carries the value for
  the sweep's durable form to consume
- the one-window-host posture recorded in the module doc (the
  durable window hosts on the kv engine when it is SQL-backed; wave
  5's pg-lo dormancy slots in without reshaping)
- stale empty-set scaffolding updated to the landed state: the
  #[allow(unused_variables)] attrs off the KvEngine methods; the
  scope notes in store.rs, backend.rs, sqlite.rs, gc.rs
- constructor unit tests: mode/threshold/window-delay introspection,
  the GC schema observed in the fresh database (window table present,
  gc_pins never), kv-only rejection wiring unchanged, and the
  dual-tier shape round-tripping end-to-end through both tiers

Verification: cargo test 62 passed (default; 5 new tests), cargo test
--all-features 117, cargo test --features mem 117, --no-default-
features --features mem 97; cargo clippy --all-targets -- -D warnings
clean (default + all-features); cargo fmt --check clean; cargo doc
--no-deps at the pre-existing warning baseline.
This commit is contained in:
glm-5.3-flash committed 2026-10-12 04:50:22 +00:00
1 parent 51d8f6525f
commit 2993df0e36
6 files changed
+673 -64

No files matched your search

+71 -9
View File
@@ -1,7 +1,7 @@
---
id: store-sqlite-construction
name: sqlite constructor wiring — the default-build store shapes
status: pending
status: completed
depends_on: [engine-sqlite, engine-sqlite-window]
scope: narrow
risk: low
@@ -61,19 +61,19 @@ a named constructor is slotting in"):
## Acceptance Criteria
- [ ] `KvEngine::Sqlite` slots in; all six kv ops dispatch; the kv
- [x] `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
- [x] `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
- [x] `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
- [x] 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
- [x] The stale empty-set scaffolding/allow notes updated to the
landed state
- [ ] `cargo test` (default) green — the default build constructs and
- [x] `cargo test` (default) green — the default build constructs and
exercises sqlite stores; `cargo clippy --all-targets -- -D
warnings` and `cargo fmt --check` green
@@ -88,8 +88,70 @@ a named constructor is slotting in"):
## Notes
> To be filled by implementation agent
- **KvCursor sub-enum (the recorded design point).** The kv cursor
dispatch went with a `KvCursor` sub-enum behind `AnyCursor`'s one
`Kv` arm (rather than a per-engine `AnyCursor::Kv*` variant pair):
per-engine variants would copy the kv materializing arm and its
consumers (the verification-on-get body, `Blob`'s drive) per engine
without adding a behavior; the sub-enum keeps `AnyCursor` a two-arm
tier dispatch. Postgres (wave 4) slots one arm into `KvCursor`.
- **`KvEngine::ensure_gc_schema` — the engine-neutral store-core
call** lives on the kv-tier enum itself: the sqlite arm forwards to
the `EngineWindowState` clause; the mem arm is structurally nothing
(the in-process engines execute the ADR-005 window protocol inline
and carry no GC schema). Both sqlite constructors dispatch through
it — the store core calls the kv engine, never a typed sqlite path,
which is the recording shape the one-window-host posture wanted.
- **The window delay** is a named shipped constant
(`DEFAULT_DELETE_WINDOW_DELAY`, 5 min, ADR-008 §2) re-exported from
`lib.rs`; both sqlite constructors take it explicitly
(`Duration`, `Duration::ZERO` the legal degenerate tuning) and the
store carries it as a `window_delay` field with a crate-internal
accessor (`Store::window_delay`) for the durable sweep form
(`store-sweep-durable-window`) to consume. The mem/local
constructors are signature-unchanged; they carry the constant,
never consulted (the inline form has no delay in effect — same
posture as the mem-only threshold field).
- **Fallibility split**: `dual_tier_sqlite_local(database, root,
threshold, window_delay)` is fallible on the database file I/O,
`ensure_gc_schema`, *and* the local root creation (all
`Err(Error::Io)` via `?`); `kv_only_sqlite(database, threshold,
window_delay)` on the first two. WAL engagement failure (e.g.
`:memory:`) is a construction error, per the engine's recorded
posture.
- `SqliteBackend` gained a `#[cfg(test)] table_exists` probe (the
sqlite_master instrument) so the store tests can observe the
schema from the facade side; sqlite.rs's own test helper now
delegates to it.
- The stale empty-set scaffolding is updated to the landed state:
the `#[allow(unused_variables)]` attrs came off the `KvEngine`
methods; the scope notes in store.rs, backend.rs
(whole-value `put` now has its in-tree callers), sqlite.rs
(nothing-constructs-the-engine), and gc.rs (the window family's
first caller) reflect the landed state. `--no-default-features`
builds (kv set genuinely empty again) still compile under their
own cfg arithmetic — verified along with the default, mem-only,
and all-features builds.
## Summary
> To be filled on completion
Sqlite slotted into the facade's engine representation (wave 3
construction; commit pending at write time): `KvEngine::Sqlite` with
all six kv-op dispatch arms, the `KvCursor` sub-enum carrying the
sqlite materializing body behind `AnyCursor`'s kv arm (design point
recorded), the two named constructors (`dual_tier_sqlite_local` — the
default-build production shape, and `kv_only_sqlite`) taking
threshold + the constructor-tunable delete-window delay
(`DEFAULT_DELETE_WINDOW_DELAY` pinned at 5 min, `0` legal),
`ensure_gc_schema` running at construction through the engine-neutral
`KvEngine` call, the one-window-host posture recorded in the module
doc (the durable window is the kv engine's when the kv engine is
SQL-backed — wave 5's pg-lo dormancy slots in without reshaping),
and all stale empty-set allow/scope notes updated to the landed
state. Verification: `cargo test` 62 passing (default build — the
5 new sqlite-construction tests construct, introspect, schema-probe,
rejection-check, and end-to-end round-trip both tiers),
`cargo test --all-features` 117, `cargo test --features mem` 117,
`--no-default-features --features mem` 97, clippy `-D warnings`
(default + all-features) clean, `cargo fmt --check` clean, and
`cargo doc --no-deps` at the pre-existing warning baseline.