alkblobs/tasks/engine-sqlite.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
engine-sqlite	sqlite kv engine — the default engine	pending		narrow	medium	component	implementation	wave-3 engines sqlite

Description

Implement the sqlite kv-tier engine (feature sqlite, default-on; ADR-007; REQ-1) against the wave-1 trait (src/backend.rs) — the first SQL-backed engine and the default build's kv engine.

• Backend impl (src/sqlite.rs, behind #[cfg(feature = "sqlite")]): the seven methods plus put_staged, opaque byte keys/values, name() -> "sqlite".
  • Schema — the POC #5 finding B5 row shape adapted to sqlite: blobs (key BLOB PRIMARY KEY, value BLOB, size INTEGER NOT NULL). The dedicated size column is what makes the indexed size column probe metadata-only: SELECT size … WHERE key = ? rides the key's index and never loads the value blob (ADR-008's size discipline).
  • WAL posture — journal_mode=WAL + synchronous=NORMAL set at open: the shipped durability tier (ADR-003; the posture honker ships and iroh's store measured). The single-writer ceiling is a documented posture, not a defect (REQ-1's economics — the module doc records it; ~1.2k objects/s under contention is an order above single-node push rates).
  • Prepared statements — rusqlite's prepare_cached discipline per the backends spec's "prepared statements" requirement.
  • has — an EXISTS probe (SELECT EXISTS(…)) — never a value load.
  • get — the materializing cursor body (kv family): the whole value loaded once (bounded by tier policy — the kv tier holds only ≤ threshold content), len() from the row's size column, reads slice the materialized value composing backend.rs's clamped. This body is also what the facade's verification-on-get re-derives over (store.rs's kv design point — no engine change needed).
  • put — CAS first-writer-wins (INSERT OR IGNORE); a re-put of an existing key is a no-op, never an overwrite.
  • put_staged — the degenerate in-memory stage (ADR-010 §1: kv bodies stage in memory and commit through the whole-value row write); append extends the buffer, commit publishes via the same INSERT OR IGNORE clause and self-discards on failure, discard drops the buffer with zero residue.
  • delete — Err(Error::Missing) when absent (rows-affected discipline); list — complete and well-formed (SELECT key); size — the indexed column probe above.
  • Virgin-store no-tables-yet tolerance — read paths treat a missing table as absent/empty, never "table does not exist" errors (POC #1 finding 2; store-api.md §Error model's virgin-store semantics). Schema creation timing (constructor CREATE TABLE IF NOT EXISTS vs lazy) is a recorded design point; the tolerance is unit-tested against a tableless database file either way.
• Blocking discipline: rusqlite is synchronous — all engine I/O runs in spawn_blocking (AGENTS convention 3; store-api.md §Concurrency posture). The connection posture (the expected shape: a single connection behind a short-held lock, the single-writer posture; a pool is not required solo) is a recorded design point. No blocking I/O on the async path; no unwrap/expect outside tests.
• Unit tests in-module: the method contract (virgin-store no-ops incl. the no-tables-yet form, CAS re-put, Missing discipline, size exactness + metadata-only), the staged-put happy path and both hygiene forms (discard → zero residue; commit failure → self-discard — a #[cfg(test)] fail-commit knob standing in for media failure, the mem engine's pattern), the pragma posture.

The engine-state window family (EngineWindowState) is engine-sqlite-window (separate task); the constructor wiring is store-sqlite-construction. This task ships the engine and its in-module unit tests only.

Acceptance Criteria

• src/sqlite.rs implements Backend completely (seven methods + put_staged) behind feature sqlite (default-on), with the materializing cursor body and the degenerate staging body
• WAL + synchronous=NORMAL set at open; prepared-statement discipline; has is an EXISTS probe; the single-writer ceiling recorded as posture in the module doc
• size reads the dedicated size column via the key index, never the value blob (metadata-only, unit-tested)
• CAS first-writer-wins on both put forms; re-put never overwrites
• Stage hygiene holds in both forms (discard → zero residue; failed commit → self-discard), unit-tested
• Virgin-store reads are no-ops including the no-tables-yet form (unit-tested against a tableless database file)
• All engine I/O in spawn_blocking; connection posture recorded
• cargo test (default — sqlite is default-on) green; cargo clippy --all-targets -- -D warnings and cargo fmt --check green

References

• docs/architecture/backends-and-dispatch.md (§kv tier — sqlite engine)
• docs/architecture/decisions/007-two-kv-engines-sqlite-and-postgres.md
• docs/architecture/decisions/003-backend-contract-and-dispatch.md (the shipped durability tier; the three numbered put rules' kv side)
• docs/architecture/decisions/010-backend-io-seams-and-fleet-state.md §1
• docs/architecture/requirements.md (REQ-1's economics)
• docs/research/poc-postgres-kv-findings.md (finding B5's row shape)
• docs/research/poc-largeblob-findings.md (finding A4's economics)
• src/backend.rs (the trait + seam contracts this implements)
• src/mem.rs (the contract-reference engine's shapes this mirrors)

Notes

To be filled by implementation agent

Summary

To be filled on completion