alkblobs/tasks/suite-column-sqlite.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
suite-column-sqlite	Conformance suite — the sqlite column (the first SQL-backed column)	completed	store-sweep-durable-window	moderate	medium	phase	implementation	wave-3 suite sqlite

Description

Grow the sqlite column — the suite's first SQL-backed column, server-less (never skips; README §SKIP posture: server-less engines' columns must always be green in every environment). The column runs in the default build (feature sqlite is default-on).

• Factories (tests/conformance/sqlite_column.rs):
  • dual-tier kv = sqlite + large = local at a column-declared threshold and the test tuning of the window delay (0 — execute-on-next-sweep);
  • kv-only(sqlite) at a column-declared threshold (the rejection row's host; threshold materializable per the README's configuration contract). Fresh isolated sqlite file per open() (temp file), idempotent teardown (remove the file), panicking-row-safe — the local column's instance-tracks-its-own-root pattern.
• Mirror the form-independent reference rows (README §The reference row set): INV-1 round-trips (content matrix × both put paths, in-body), INV-2 dedup (same-path + cross-path legs), INV-3 stage hygiene (the degenerate kv stage form via the injectable failure modes — mid-stream Io, declared-len Verification), INV-6 stat discipline, and the kv-only rejection row (threshold-agnostic by discovery, unchanged).
• The sweep rows are schedule-relative on this column. The reference set's single-sweep exact-count rows are the inline-form host's (mem); the durable form's semantics differ (staged this sweep, executed by the next — ADR-012 §6.7). The sqlite column grows its own durable-schedule rows (concrete-factory per README §Columns beyond the reference set, ADR-stamped, traced):
  • exact counts across two sweeps (sweep 1 stages N, deletes nothing; sweep 2 executes exactly N — deleted + cancelled == N against the staged set) over the full protection set;
  • the sweep-vs-put race across the window delay (a put landing during the window survives the executing sweep; the unpinned twin deletes);
  • the abort shapes (NoLivenessSources/ProtectFailed/ SweeperLock — form-independent, abort before staging; these mirror directly);
  • INV-5 list correctness through durable-schedule outcomes (exact counts, never list comparison).
• The dual-tier dispatch rows mirror the local column's family (pure-function routing, threshold boundaries, fall-through per op) with the placement oracle adapted: both tiers are on disk now — kv entries live in the sqlite file, large entries under the local root; the oracle distinguishes by medium (the sqlite file vs the root's committed files).
• Virgin-store rows: reads are no-ops on a fresh file; the no-tables-yet tolerance form.
• README amendments (the convention's normative test-side home):
  • the schedule-relative reading of INV-4/INV-5 for SQL-backed columns — the durable form's exact counts are asserted relative to the staged schedule (ADR-012 §6.7); the reference set's single-sweep rows are the inline-form host's, and SQL-backed columns run the durable-schedule equivalents (the mirror convention's recorded amendment);
  • the column inventory (§Columns beyond the reference set grows the sqlite rows table);
  • current state (three columns; the default-build column).
• Structural factory tests (the mem column's pattern): factory isolation (fresh file per open, nothing shared) and teardown-against-a-panicking-row.

Acceptance Criteria

• The sqlite column green server-less: the mirrored form-independent reference rows + the durable-schedule sweep rows + the dispatch rows + the virgin-store rows, every row ADR-stamped and traceable to the backlog
• The schedule-relative INV-4/INV-5 reading recorded in README (the mirror convention's amendment, citing ADR-012 §6.7)
• Factory isolation + idempotent teardown hold (fresh file per open; teardown safe against a panicking row), structurally exercised
• cargo test (default) green — the column runs in the default build; cargo clippy --all-targets -- -D warnings and cargo fmt --check green

References

• tests/conformance/README.md (the conventions this grows against; §SKIP posture, §Columns beyond the reference set)
• tests/conformance/rows.rs (the reference row set being mirrored)
• tests/conformance/local_column.rs (the dual-tier column pattern)
• tests/conformance/backlog.rs (INV-1…7 entries)
• docs/architecture/store-api.md (§Invariants — the test gate)
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.7 (the schedule the sweep rows assert against)
• docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md §2 (mem's reference role; INV-7)

Notes

The column as it landed (tests/conformance/sqlite_column.rs, 17 tests):

• Factories: dual-tier sqlite+local (the default-build production shape, DualTierSqliteFactory) and kv-only(sqlite) (KvOnlySqliteFactory), each instance-tracking the temp sites it vends (a private temp directory per open holding pool.db and the local root; teardown remove_dir_alls it — idempotent, NotFound tolerated, panicking-row-safe, one runner per instance), with the column-declared threshold (1024) and the test tuning of the window delay (Duration::ZERO — execute-on-next-sweep). The module is #[cfg(feature = "sqlite")] — default-on, so the column runs in every default cargo test.
• The medium oracle distinguishes by medium: the dual-tier rows count the sqlite file's blobs rows (the kv tier) vs the local root's committed files (the large tier), plus gc_window rows (the durable schedule observer) — via the test's own independent connection. The shared helpers (committed_file_count, staging_file_count, slice_digest, LatchProtect) moved to rows.rs (pub(crate), the columns' shared fixtures) so the sqlite column reuses them without the mem gate.
• Mirrored verbatim (form-independent, from rows.rs): INV-1 round-trips, INV-6 stat discipline, the NoLivenessSources/ ProtectFailed abort shapes, and the kv-only rejection row (against kv-only(sqlite); unchanged, threshold-agnostic by discovery).
• Durable-schedule rows (the column's own, concrete-factory, ADR-stamped, traced): INV-2 dedup and INV-3 stage hygiene with counts read against the staged schedule (the sweep-counting rows' amendment), the two-sweep exact-count row over the full protection set (both tiers, the window observed), the race across the window delay (a re-put landing during the window survives the executing sweep via execution-time re-arbitration; the unpinned twin deletes; both put paths in-body over both tiers), the holder-stages-only lease shape (the reference SweeperLock row's schedule-relative form), and INV-5 list correctness through durable-schedule outcomes.
• Dispatch rows mirror the local column's family (pure-function routing, threshold boundaries at the tuned + shipped-default thresholds, fall-through per op) with the placement oracle adapted by medium. Virgin-store row: reads are no-ops on a fresh file (pool, window, and committed tree all empty); the no-tables-yet tolerance itself is engine-instrumented (src/sqlite.rs — the constructor always ensures the schema), this row being the facade form. Structural factory tests: fresh isolated opens (distinct private sqlite files and roots, medium-observable) and teardown-against-a-panicking-row (files really removed).
• README amendments: §The schedule-relative reading for SQL-backed columns (the mirror convention's amendment, citing ADR-012 §6.7 — staged-this-sweep / executed-next-sweep, which rows carry it, which mirror verbatim), the sqlite rows table in §Columns beyond the reference set, and Current state (three columns; the default-build column). main.rs's module doc names the column.

Summary

The sqlite column — the suite's first SQL-backed column — is green: the default-build production shape (kv = sqlite + large = local, feature sqlite default-on) runs the form-independent reference rows verbatim against its factories, grows the durable-schedule sweep rows whose exact counts are asserted relative to the staged schedule (ADR-012 §6.7: staged this sweep, executed by the next — two-sweep counts over the full protection set, the race across the window delay, the holder-stages-only lease shape, INV-5 through outcomes, and the schedule-relative INV-2/INV-3 readings), and the dispatch rows with the medium oracle distinguishing the sqlite file's rows from the root's committed files. Every row ADR-stamped and traced; the schedule-relative INV-4/INV-5 reading is recorded in the README (the mirror convention's amendment); factory isolation (fresh site per open) and idempotent panicking-row-safe teardown hold structurally. The column never skips and runs in the default build (17 tests).

Verification: cargo test green (default: 69 lib + 19 conformance + 3 git-interop), cargo test --features mem green (124 lib + 54 conformance), cargo check --all-features --tests green, cargo clippy --all-targets -- -D warnings green, cargo fmt --check green (fmt applied).