solo-storage 0.11.4

Solo: SQLite + SQLCipher persistence layer
Documentation

Solo storage: SQLite + SQLCipher persistence layer.

Concurrency invariants (per ADR-0003)

  • Writes go through WriteHandle; reads go through ReaderPool. Direct connection access is an anti-pattern outside the actor + pool.
  • The writer connection opens once and is owned by the writer thread for the daemon's lifetime.
  • The read pool's post_create hook binds the raw SQLCipher key on each new connection.
  • pending_index ordering is always SQL COMMIT → HNSW.add → drain row. Never reverse.
  • Arc<dyn VectorIndex + Send + Sync> is shared between the writer and the read pool; concurrency is provided by the impl (e.g., hnsw_rs's internal parking_lot::RwLock), not by application-level locks.

Module layout

Commit 1.1 — solo init building blocks:

  • path_validation — refuse cloud-sync data dirs.
  • key_material — Argon2id passphrase → 32-byte SQLCipher key.
  • config — solo.config.toml (salt + embedder identity).
  • migration — runner + the v0 schema (migrations/0001_initial.sql).
  • lockfile — RAII solo.lock to serialize concurrent runs.
  • init — orchestrator: solo_storage::init(params).

Commit 1.2 — single-writer actor + read pool:

  • writer — WriterActor, WriteHandle, WriteCommand.
  • reader — ReaderPool (deadpool-sqlite + post_create raw-key).

Commit 1.3 — HNSW backing for solo_core::VectorIndex + snapshot I/O:

  • vector_index — HnswIndex (hnsw_rs wrapper), HnswFactory.
  • snapshot — atomic two-file save (live/_bak/_tmp basenames) + load/load_bak per ADR-0003 §"Startup file-existence decision tree".
  • recovery — replay_pending_index, detect_drift. Used by the daemon-main startup chain (commit 1.5).

Embedder impls:

  • embedder::stub — StubEmbedder, deterministic hash-based F32 embedder for tests + offline development.
  • embedder::ollama — OllamaEmbedder, real semantic embeddings via a local Ollama daemon (/api/embeddings). The recommended production backend since v0.5.1; default for new deployments.

(v0.5.x also shipped a BGE-M3 / candle-transformers backend; it was deprecated in v0.5.0 and removed in v0.6.0. The replacement is OllamaEmbedder.)

Commit 1.5+ (daemon main + signal handlers) lands in subsequent files; the surfaces here are stable for that wiring.