@loomwork/plugin-sqlite 0.0.0-stage → 0.1.0

package/src/SqliteMemoryStore.ts

@@ -0,0 +1,160 @@
+import type { MemoryEntry, MemorySearchOptions, MemoryStore } from "@loomwork/memory";
+import { clampSearchLimit, queryTerms, searchableText } from "@loomwork/memory";
+import Database from "better-sqlite3";
+
+interface EntryRow {
+  entry: string;
+}
+
+/**
+ * SQLite-backed {@link MemoryStore} — the zero-server durable agent memory. Point it
+ * at the same DB file as the SqliteEventStore so one backup captures events + memory.
+ * Own idempotent migration, same pattern as SqliteTimerStore/SqliteDurableStateStore.
+ *
+ * A key names an ordered list, so the table needs an insertion key of its own: entries
+ * routinely share a timestamp and `ORDER BY timestamp` would reshuffle a conversation.
+ * `AUTOINCREMENT` (not bare rowid) makes the monotonicity a schema-level guarantee
+ * rather than an argument about rowid reuse after a `clear`.
+ *
+ * `replace` is one transaction, which is the whole reason it is on the SPI: MemoryRuntime
+ * rewrites a list on every TTL/maxEntries eviction, and a crash between the delete and the
+ * re-insert would make routine eviction the thing that loses the scope.
+ *
+ * `remove` (ADR 0091) is one indexed `DELETE` matching `json_extract(entry, '$.id')` — the
+ * id is read from the stored JSON rather than duplicated into a column, so nothing can
+ * drift between what `read` returns and what a delete matches, and a database written
+ * before this shipped needs no migration.
+ *
+ * `search` rides an FTS5 index over `searchableText(entry)`, held in an EXTERNAL-CONTENT
+ * table so the text is indexed but not stored twice, and synchronised by triggers so a
+ * `clear`/`replace` cannot leave the index describing entries that no longer exist. FTS5's
+ * `rank` is a BM25 score where LOWER is better, hence `ORDER BY rank` ascending.
+ */
+export class SqliteMemoryStore implements MemoryStore {
+  private readonly db: Database.Database;
+  private readonly appendStmt: Database.Statement;
+  private readonly readStmt: Database.Statement;
+  private readonly clearStmt: Database.Statement;
+  private readonly removeStmt: Database.Statement;
+  private readonly searchStmt: Database.Statement;
+  private readonly replaceTxn: (key: string, entries: readonly MemoryEntry[]) => void;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS memory_entries (
+          seq INTEGER PRIMARY KEY AUTOINCREMENT,
+          key TEXT NOT NULL,
+          entry TEXT NOT NULL,
+          text TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_memory_entries_key
+          ON memory_entries (key, seq ASC);
+        -- Removal by entry id (ADR 0091). An EXPRESSION index over the stored JSON, not
+        -- a column: the entry is already persisted whole, so an id round-trips with no
+        -- schema change and no migration of rows written before this shipped -- and a
+        -- column would be a second copy able to disagree with the one a read returns.
+        CREATE INDEX IF NOT EXISTS idx_memory_entries_id
+          ON memory_entries (key, json_extract(entry, '$.id'))
+          WHERE json_extract(entry, '$.id') IS NOT NULL;
+
+        CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+          text, content='memory_entries', content_rowid='seq'
+        );
+        -- External content: the index holds no copy of the row, so it must be told about
+        -- every insert and delete. Entries are never updated, so there is no update trigger.
+        CREATE TRIGGER IF NOT EXISTS memory_entries_ai AFTER INSERT ON memory_entries BEGIN
+          INSERT INTO memory_fts(rowid, text) VALUES (new.seq, new.text);
+        END;
+        CREATE TRIGGER IF NOT EXISTS memory_entries_ad AFTER DELETE ON memory_entries BEGIN
+          INSERT INTO memory_fts(memory_fts, rowid, text) VALUES ('delete', old.seq, old.text);
+        END;
+      `);
+      this.appendStmt = this.db.prepare(
+        "INSERT INTO memory_entries (key, entry, text) VALUES (?, ?, ?)"
+      );
+      this.readStmt = this.db.prepare(
+        "SELECT entry FROM memory_entries WHERE key = ? ORDER BY seq ASC"
+      );
+      this.clearStmt = this.db.prepare("DELETE FROM memory_entries WHERE key = ?");
+      // `json_each` over ONE json-array parameter, not a generated `IN (?,?,?…)`: a
+      // document with 200 chunks would otherwise be a 200-placeholder statement that has
+      // never been prepared before, and better-sqlite3 caches by SQL text.
+      this.removeStmt = this.db.prepare(
+        `DELETE FROM memory_entries
+          WHERE key = ?
+            AND json_extract(entry, '$.id') IN (SELECT value FROM json_each(?))`
+      );
+      this.searchStmt = this.db.prepare(
+        `SELECT e.entry FROM memory_fts
+           JOIN memory_entries e ON e.seq = memory_fts.rowid
+          WHERE memory_fts MATCH ? AND e.key = ?
+          ORDER BY memory_fts.rank
+          LIMIT ?`
+      );
+      this.replaceTxn = this.db.transaction((key: string, entries: readonly MemoryEntry[]) => {
+        this.clearStmt.run(key);
+        for (const entry of entries)
+          this.appendStmt.run(key, JSON.stringify(entry), searchableText(entry));
+      });
+    } catch (err) {
+      this.db.close(); // don't leak the file handle if setup fails on a bad/locked file
+      throw err;
+    }
+  }
+
+  async append(key: string, entry: MemoryEntry): Promise<void> {
+    this.appendStmt.run(key, JSON.stringify(entry), searchableText(entry));
+  }
+
+  async read(key: string): Promise<MemoryEntry[]> {
+    const rows = this.readStmt.all(key) as EntryRow[];
+    return rows.map((row) => JSON.parse(row.entry) as MemoryEntry);
+  }
+
+  async clear(key: string): Promise<void> {
+    this.clearStmt.run(key);
+  }
+
+  async replace(key: string, entries: readonly MemoryEntry[]): Promise<void> {
+    this.replaceTxn(key, entries);
+  }
+
+  /**
+   * Delete by entry id. The FTS index needs no special handling: rows are deleted, so the
+   * existing AFTER DELETE trigger takes them out of `memory_fts` — which is the reason
+   * this is a row delete and not a rewrite of the `entry` JSON.
+   *
+   * An entry with no id has `json_extract(...) IS NULL`, and `NULL IN (...)` is NULL —
+   * never true — so anonymous entries cannot be removed by any list of ids, including one
+   * containing the strings "null" or "undefined".
+   */
+  async remove(key: string, ids: readonly string[]): Promise<void> {
+    if (ids.length === 0) return;
+    this.removeStmt.run(key, JSON.stringify(ids));
+  }
+
+  async search(key: string, query: string, opts: MemorySearchOptions = {}): Promise<MemoryEntry[]> {
+    const terms = queryTerms(query);
+    if (terms.length === 0) return [];
+    // `queryTerms`, not `tokenize`: OR-ing the same term 20,000 times cannot change which
+    // rows match and took 32.7 SECONDS here before it was deduplicated.
+    //
+    // Building the MATCH from TERMS, never from the raw question, is what keeps FTS5's
+    // expression syntax (`*`, `NEAR`, `AND`, a bare `-`) out of it: a user question passed
+    // through is parsed as operators, and either raises a syntax error or quietly means
+    // something else. `tokenize` already yields lowercase alphanumerics — which cannot be
+    // FTS5 keywords, those being uppercase — and the quoting below is the second belt, so
+    // that widening what counts as a term later cannot reopen this.
+    const match = terms.map((term) => `"${term}"`).join(" OR ");
+    const rows = this.searchStmt.all(match, key, clampSearchLimit(opts.limit)) as EntryRow[];
+    return rows.map((row) => JSON.parse(row.entry) as MemoryEntry);
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/SqliteReadModelStore.ts

@@ -0,0 +1,378 @@
+import type {
+  FoldedApply,
+  FoldedApplyResult,
+  FoldedRecord,
+  FoldedSelector,
+  ReadModelPage,
+  ReadModelQuery,
+  ReadModelRow,
+  ReadModelScalar,
+  ReadModelStore,
+} from "@loomwork/plugin-read-model";
+import {
+  assertFoldedSelector,
+  assertManyKeys,
+  assertPurgeFilter,
+  clampQueryLimit,
+  foldedSelectorColumn,
+  parseQueryCursor,
+} from "@loomwork/plugin-read-model";
+import Database from "better-sqlite3";
+
+interface RowRecord {
+  row_id: string;
+  execution_id: string;
+  sequence: number;
+  timestamp: number;
+  kind: string;
+  fields: string;
+  value: string;
+}
+
+interface FoldedDbRow {
+  execution_id: string;
+  app_key: string | null;
+  scope: string | null;
+  sequence: number;
+  state: string | null;
+  erased: number;
+}
+
+function toFolded(r: FoldedDbRow): FoldedRecord {
+  return {
+    executionId: r.execution_id,
+    key: r.app_key,
+    scope: r.scope,
+    sequence: r.sequence,
+    state: r.state === null ? null : JSON.parse(r.state),
+    erased: r.erased === 1,
+  };
+}
+
+/**
+ * SQLite-backed {@link ReadModelStore} (RM, issue #183). Point it at the same
+ * DB file as the SqliteEventStore so one backup captures log + read models.
+ * Own idempotent migration, same pattern as SqliteDurableStateStore. Field
+ * equality queries use `json_extract` over the JSON `fields` column; keyset
+ * pagination uses row-value comparison over (timestamp, sequence, row_id).
+ */
+export class SqliteReadModelStore implements ReadModelStore {
+  private readonly db: Database.Database;
+  // Audit fix (DS&A rank 2): statements are prepared ONCE — apply-heavy
+  // catch-ups no longer re-parse identical SQL per call.
+  private readonly insertRowStmt: Database.Statement;
+  private readonly upsertMarkStmt: Database.Statement;
+  private readonly watermarkStmt: Database.Statement;
+  private readonly watermarkedStmt: Database.Statement;
+  private readonly clearRowsStmt: Database.Statement;
+  private readonly clearMarksStmt: Database.Statement;
+  private readonly foldHeaderStmt: Database.Statement;
+  private readonly upsertFoldHeaderStmt: Database.Statement;
+  private readonly dropFoldStatesStmt: Database.Statement;
+  private readonly dropFoldHeaderStmt: Database.Statement;
+  private readonly applyFoldedStmt: Database.Statement;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS read_model_rows (
+          model_id TEXT NOT NULL,
+          row_id TEXT NOT NULL,
+          execution_id TEXT NOT NULL,
+          sequence INTEGER NOT NULL,
+          timestamp INTEGER NOT NULL,
+          kind TEXT NOT NULL,
+          fields TEXT NOT NULL,
+          value TEXT NOT NULL,
+          PRIMARY KEY (model_id, row_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_rm_rows_order
+          ON read_model_rows (model_id, kind, timestamp, sequence);
+        CREATE TABLE IF NOT EXISTS read_model_watermarks (
+          model_id TEXT NOT NULL,
+          execution_id TEXT NOT NULL,
+          sequence INTEGER NOT NULL,
+          PRIMARY KEY (model_id, execution_id)
+        );
+        CREATE TABLE IF NOT EXISTS read_model_folds (
+          model_id TEXT PRIMARY KEY,
+          version TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS read_model_state (
+          model_id TEXT NOT NULL,
+          execution_id TEXT NOT NULL,
+          app_key TEXT,
+          scope TEXT,
+          sequence INTEGER NOT NULL,
+          state TEXT,
+          erased INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (model_id, execution_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_rm_state_key
+          ON read_model_state (model_id, app_key) WHERE app_key IS NOT NULL;
+        CREATE INDEX IF NOT EXISTS idx_rm_state_scope
+          ON read_model_state (model_id, scope) WHERE scope IS NOT NULL;
+      `);
+      this.insertRowStmt = this.db.prepare(
+        `INSERT OR IGNORE INTO read_model_rows
+           (model_id, row_id, execution_id, sequence, timestamp, kind, fields, value)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+      );
+      this.upsertMarkStmt = this.db.prepare(
+        `INSERT INTO read_model_watermarks (model_id, execution_id, sequence)
+         VALUES (?, ?, ?)
+         ON CONFLICT (model_id, execution_id)
+         DO UPDATE SET sequence = MAX(sequence, excluded.sequence)`
+      );
+      this.watermarkStmt = this.db.prepare(
+        "SELECT sequence FROM read_model_watermarks WHERE model_id = ? AND execution_id = ?"
+      );
+      this.watermarkedStmt = this.db.prepare(
+        "SELECT execution_id FROM read_model_watermarks WHERE model_id = ?"
+      );
+      this.clearRowsStmt = this.db.prepare("DELETE FROM read_model_rows WHERE model_id = ?");
+      this.clearMarksStmt = this.db.prepare("DELETE FROM read_model_watermarks WHERE model_id = ?");
+      this.foldHeaderStmt = this.db.prepare(
+        "SELECT version FROM read_model_folds WHERE model_id = ?"
+      );
+      this.upsertFoldHeaderStmt = this.db.prepare(
+        `INSERT INTO read_model_folds (model_id, version) VALUES (?, ?)
+         ON CONFLICT (model_id) DO UPDATE SET version = excluded.version`
+      );
+      this.dropFoldStatesStmt = this.db.prepare("DELETE FROM read_model_state WHERE model_id = ?");
+      this.dropFoldHeaderStmt = this.db.prepare("DELETE FROM read_model_folds WHERE model_id = ?");
+      // One statement: header check + monotonic CAS. RETURNING reports the (unchanged)
+      // erased flag so advancing a tombstone is "applied-erased" and keeps state NULL.
+      this.applyFoldedStmt = this.db.prepare(
+        `INSERT INTO read_model_state
+           (model_id, execution_id, app_key, scope, sequence, state, erased)
+         SELECT ?, ?, ?, ?, ?, ?, 0
+         WHERE EXISTS (SELECT 1 FROM read_model_folds WHERE model_id = ? AND version = ?)
+         ON CONFLICT (model_id, execution_id) DO UPDATE
+           SET sequence = excluded.sequence,
+               state = CASE WHEN read_model_state.erased = 1 THEN NULL ELSE excluded.state END,
+               app_key = COALESCE(excluded.app_key, read_model_state.app_key),
+               scope = COALESCE(excluded.scope, read_model_state.scope)
+           WHERE read_model_state.sequence < excluded.sequence
+         RETURNING erased`
+      );
+    } catch (err) {
+      this.db.close(); // don't leak the file handle if setup fails on a bad/locked file
+      throw err;
+    }
+  }
+
+  async apply(
+    modelId: string,
+    executionId: string,
+    upToSequence: number,
+    rows: readonly ReadModelRow[]
+  ): Promise<void> {
+    this.db.transaction(() => {
+      for (const row of rows) {
+        this.insertRowStmt.run(
+          modelId,
+          row.rowId,
+          row.executionId,
+          row.sequence,
+          row.timestamp,
+          row.kind,
+          JSON.stringify(row.fields),
+          JSON.stringify(row.value ?? null)
+        );
+      }
+      this.upsertMarkStmt.run(modelId, executionId, upToSequence);
+    })();
+  }
+
+  async watermark(modelId: string, executionId: string): Promise<number | null> {
+    const row = this.watermarkStmt.get(modelId, executionId) as { sequence: number } | undefined;
+    return row?.sequence ?? null;
+  }
+
+  async watermarkedExecutions(modelId: string): Promise<string[]> {
+    const rows = this.watermarkedStmt.all(modelId) as { execution_id: string }[];
+    return rows.map((r) => r.execution_id);
+  }
+
+  async query(modelId: string, q: ReadModelQuery = {}): Promise<ReadModelPage> {
+    const desc = q.order === "desc";
+    const limit = clampQueryLimit(q.limit);
+    const clauses = ["model_id = ?"];
+    const params: unknown[] = [modelId];
+    if (q.kind !== undefined) {
+      clauses.push("kind = ?");
+      params.push(q.kind);
+    }
+    for (const [field, value] of Object.entries(q.where ?? {})) {
+      const path = `$."${field.split('"').join('""')}"`;
+      if (value === null) {
+        clauses.push("json_extract(fields, ?) IS NULL");
+        params.push(path);
+      } else {
+        clauses.push("json_extract(fields, ?) = ?");
+        params.push(path, typeof value === "boolean" ? (value ? 1 : 0) : value);
+      }
+    }
+    if (q.cursor !== undefined) {
+      const [ts, seq, rowId] = parseQueryCursor(q.cursor);
+      clauses.push(`(timestamp, sequence, row_id) ${desc ? "<" : ">"} (?, ?, ?)`);
+      params.push(ts, seq, rowId);
+    }
+    const dir = desc ? "DESC" : "ASC";
+    const records = this.db
+      .prepare(
+        `SELECT row_id, execution_id, sequence, timestamp, kind, fields, value
+         FROM read_model_rows WHERE ${clauses.join(" AND ")}
+         ORDER BY timestamp ${dir}, sequence ${dir}, row_id ${dir}
+         LIMIT ?`
+      )
+      .all(...params, limit + 1) as RowRecord[];
+
+    const page = records.slice(0, limit).map(
+      (r): ReadModelRow => ({
+        rowId: r.row_id,
+        executionId: r.execution_id,
+        sequence: r.sequence,
+        timestamp: r.timestamp,
+        kind: r.kind,
+        fields: JSON.parse(r.fields),
+        value: JSON.parse(r.value),
+      })
+    );
+    const last = page[page.length - 1];
+    return {
+      rows: page,
+      ...(records.length > limit &&
+        last !== undefined && {
+          nextCursor: JSON.stringify([last.timestamp, last.sequence, last.rowId]),
+        }),
+    };
+  }
+
+  async purge(modelId: string, where: Record<string, ReadModelScalar>): Promise<number> {
+    assertPurgeFilter(where);
+    // Same `json_extract` equality the query path uses, so a purge deletes exactly the
+    // rows the equivalent query would have returned. Not prepared once: the clause shape
+    // varies with the filter's field set, and an erasure is a lifecycle call, not a hot path.
+    const clauses = ["model_id = ?"];
+    const params: unknown[] = [modelId];
+    for (const [field, value] of Object.entries(where)) {
+      const path = `$."${field.split('"').join('""')}"`;
+      if (value === null) {
+        clauses.push("json_extract(fields, ?) IS NULL");
+        params.push(path);
+      } else {
+        clauses.push("json_extract(fields, ?) = ?");
+        params.push(path, typeof value === "boolean" ? (value ? 1 : 0) : value);
+      }
+    }
+    // Watermarks are deliberately left alone (SPI contract) — deleting one would make the
+    // next catch-up re-derive the rows just erased.
+    const info = this.db
+      .prepare(`DELETE FROM read_model_rows WHERE ${clauses.join(" AND ")}`)
+      .run(...params);
+    return info.changes;
+  }
+
+  async clear(modelId: string): Promise<void> {
+    this.db.transaction(() => {
+      this.clearRowsStmt.run(modelId);
+      this.clearMarksStmt.run(modelId);
+      // Folded state (ADR 0132): this model only. Tables are created with the others in
+      // the constructor, so clear never has to create anything.
+      this.dropFoldStatesStmt.run(modelId);
+      this.dropFoldHeaderStmt.run(modelId);
+    })();
+  }
+
+  // ── Folded state (ADR 0132 D3, D5, D6, D12) ──────────────────────────────
+
+  async beginFold(modelId: string, foldVersion: string): Promise<{ rebuilt: boolean }> {
+    // IMMEDIATE: read-then-write must take the write lock up front, or a second process
+    // in WAL mode fails with SQLITE_BUSY_SNAPSHOT when upgrading a stale read snapshot.
+    return this.db
+      .transaction(() => {
+        const prior = this.foldHeaderStmt.get(modelId) as { version: string } | undefined;
+        this.upsertFoldHeaderStmt.run(modelId, foldVersion);
+        if (prior === undefined || prior.version === foldVersion) return { rebuilt: false };
+        this.dropFoldStatesStmt.run(modelId);
+        return { rebuilt: true };
+      })
+      .immediate();
+  }
+
+  async applyFolded(a: FoldedApply): Promise<FoldedApplyResult> {
+    // IMMEDIATE for the same reason: the miss path reads the header after the write attempt.
+    return this.db
+      .transaction((): FoldedApplyResult => {
+        const hit = this.applyFoldedStmt.get(
+          a.modelId,
+          a.executionId,
+          a.key ?? null,
+          a.scope ?? null,
+          a.upToSequence,
+          a.state === null || a.state === undefined ? null : JSON.stringify(a.state),
+          a.modelId,
+          a.foldVersion
+        ) as { erased: number } | undefined;
+        if (hit !== undefined) return hit.erased === 1 ? "applied-erased" : "applied";
+        const hdr = this.foldHeaderStmt.get(a.modelId) as { version: string } | undefined;
+        return hdr?.version === a.foldVersion ? "stale" : "version-mismatch";
+      })
+      .immediate();
+  }
+
+  async getFolded(modelId: string, executionIds: readonly string[]): Promise<FoldedRecord[]> {
+    assertManyKeys(executionIds, "getFolded");
+    const ids = [...new Set(executionIds)];
+    if (ids.length === 0) return [];
+    const rows = this.db
+      .prepare(
+        `SELECT execution_id, app_key, scope, sequence, state, erased FROM read_model_state
+         WHERE model_id = ? AND execution_id IN (${ids.map(() => "?").join(",")})`
+      )
+      .all(modelId, ...ids) as FoldedDbRow[];
+    const byId = new Map(rows.map((r) => [r.execution_id, toFolded(r)]));
+    return ids.flatMap((id) => {
+      const r = byId.get(id);
+      return r === undefined ? [] : [r];
+    });
+  }
+
+  async getFoldedByKey(modelId: string, keys: readonly string[]): Promise<FoldedRecord[]> {
+    assertManyKeys(keys, "getFoldedByKey");
+    const uniq = [...new Set(keys)];
+    if (uniq.length === 0) return [];
+    // BINARY collation = memcmp over UTF-8 = code-point order (ADR 0132), explicit so a
+    // future column collation can never change it.
+    const rows = this.db
+      .prepare(
+        `SELECT execution_id, app_key, scope, sequence, state, erased FROM read_model_state
+         WHERE model_id = ? AND app_key IN (${uniq.map(() => "?").join(",")})
+         ORDER BY execution_id COLLATE BINARY`
+      )
+      .all(modelId, ...uniq) as FoldedDbRow[];
+    return rows.map(toFolded);
+  }
+
+  async purgeFolded(modelId: string, selector: FoldedSelector): Promise<number> {
+    assertFoldedSelector(selector);
+    const [col, val] = foldedSelectorColumn(selector);
+    // Tombstone, never delete: the row IS the watermark (ADR 0132 D12). `col` is one of
+    // three literals from foldedSelectorColumn, never caller input.
+    return this.db
+      .prepare(
+        `UPDATE read_model_state SET state = NULL, erased = 1
+         WHERE model_id = ? AND ${col} = ? AND erased = 0`
+      )
+      .run(modelId, val).changes;
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/SqliteSnapshotStore.ts

@@ -0,0 +1,157 @@
+import type { ExecutionState } from "@loomwork/core";
+import {
+  type Snapshot,
+  type SnapshotCodecName,
+  type SnapshotStore,
+  assertSnapshotCodecAvailable,
+  decodeState,
+  encodeState,
+  parseSnapshotCodec,
+} from "@loomwork/snapshot-runtime";
+import Database from "better-sqlite3";
+import { migrate } from "./snapshotSchema";
+
+interface SnapshotRow {
+  id: string;
+  execution_id: string;
+  workflow_id: string;
+  sequence: number;
+  // TEXT for a pre-codec row (JSON text); a BLOB (Buffer) for an ADR 0141 codec frame. SQLite is dynamically
+  // typed, so the TEXT-declared column holds either; the storage class IS the format discriminator.
+  state: string | Buffer;
+  created_at: number;
+}
+
+export interface SqliteSnapshotStoreOptions {
+  /**
+   * ADR 0141 - how NEW snapshots are written. `"none"` (default): JSON text, byte-identical to before.
+   * `"zstd"`: a BLOB frame (format byte + zstd-compressed JSON) in the same `state` column. Reads accept
+   * BOTH whatever this is set to, and nothing is rewritten. Throws at construction on a Node without zstd
+   * (>= 22.15). No schema change: SQLite's column affinity keeps a BLOB a BLOB.
+   */
+  codec?: SnapshotCodecName;
+}
+
+function rowToSnapshot(row: SnapshotRow): Snapshot {
+  return {
+    id: row.id,
+    executionId: row.execution_id,
+    workflowId: row.workflow_id,
+    sequence: row.sequence,
+    state: (typeof row.state === "string"
+      ? JSON.parse(row.state)
+      : decodeState(row.state)) as ExecutionState,
+    createdAt: row.created_at,
+  };
+}
+
+export class SqliteSnapshotStore implements SnapshotStore {
+  private readonly db: Database.Database;
+  /** ADR 0141 - the codec new snapshots are written with (structural; `ProfilingSnapshotStore` reads it). */
+  readonly snapshotCodec: SnapshotCodecName;
+
+  constructor(dbPath: string, options: SqliteSnapshotStoreOptions = {}) {
+    this.snapshotCodec = parseSnapshotCodec(options.codec);
+    assertSnapshotCodecAvailable(this.snapshotCodec);
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      migrate(this.db);
+    } catch (err) {
+      this.db.close(); // don't leak the file handle if setup fails on a bad/locked file
+      throw err;
+    }
+  }
+
+  async save(snapshot: Snapshot): Promise<void> {
+    this.db
+      .prepare<[string, string, string, number, string | Buffer, number]>(`
+        INSERT OR REPLACE INTO snapshots (id, execution_id, workflow_id, sequence, state, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `)
+      .run(
+        snapshot.id,
+        snapshot.executionId,
+        snapshot.workflowId,
+        snapshot.sequence,
+        this.snapshotCodec === "none"
+          ? JSON.stringify(snapshot.state)
+          : encodeState(snapshot.state, this.snapshotCodec),
+        snapshot.createdAt
+      );
+  }
+
+  async loadLatest(executionId: string): Promise<Snapshot | null> {
+    const row = this.db
+      .prepare<[string], SnapshotRow>(
+        "SELECT * FROM snapshots WHERE execution_id = ? ORDER BY sequence DESC LIMIT 1"
+      )
+      .get(executionId);
+    return row ? rowToSnapshot(row) : null;
+  }
+
+  async loadAt(executionId: string, sequence: number): Promise<Snapshot | null> {
+    const row = this.db
+      .prepare<[string, number], SnapshotRow>(
+        "SELECT * FROM snapshots WHERE execution_id = ? AND sequence = ?"
+      )
+      .get(executionId, sequence);
+    return row ? rowToSnapshot(row) : null;
+  }
+
+  async loadLatestBefore(executionId: string, sequence: number): Promise<Snapshot | null> {
+    const row = this.db
+      .prepare<[string, number], SnapshotRow>(
+        "SELECT * FROM snapshots WHERE execution_id = ? AND sequence <= ? ORDER BY sequence DESC LIMIT 1"
+      )
+      .get(executionId, sequence);
+    return row ? rowToSnapshot(row) : null;
+  }
+
+  async deleteExecution(executionId: string): Promise<void> {
+    this.db.prepare<[string]>("DELETE FROM snapshots WHERE execution_id = ?").run(executionId);
+  }
+
+  async listSequences(
+    executionId: string,
+    range: { readonly after?: number; readonly before?: number } = {}
+  ): Promise<number[]> {
+    // A bound the caller omitted is simply absent from the WHERE (a sentinel would drop a row at it).
+    const where = ["execution_id = ?"];
+    const args: Array<string | number> = [executionId];
+    if (range.after !== undefined) {
+      where.push("sequence > ?");
+      args.push(range.after);
+    }
+    if (range.before !== undefined) {
+      where.push("sequence < ?");
+      args.push(range.before);
+    }
+    const rows = this.db
+      .prepare<Array<string | number>, { sequence: number }>(
+        `SELECT sequence FROM snapshots WHERE ${where.join(" AND ")} ORDER BY sequence`
+      )
+      .all(...args);
+    return rows.map((r) => r.sequence);
+  }
+
+  async pruneSnapshots(
+    executionId: string,
+    range: { readonly after: number; readonly before: number },
+    keep: readonly number[] = []
+  ): Promise<number> {
+    // One statement. The keep-set is a bound JSON array, not an interpolated list.
+    const info = this.db
+      .prepare<[string, number, number, string]>(
+        `DELETE FROM snapshots WHERE execution_id = ? AND sequence > ? AND sequence < ?
+         AND sequence NOT IN (SELECT value FROM json_each(?))`
+      )
+      .run(executionId, range.after, range.before, JSON.stringify(keep));
+    return info.changes;
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}