@loomwork/plugin-sqlite 0.0.0-stage → 0.1.0

package/dist/SqliteMemoryStore.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteMemoryStore = void 0;
+const memory_1 = require("@loomwork/memory");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+/**
+ * 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.
+ */
+class SqliteMemoryStore {
+    db;
+    appendStmt;
+    readStmt;
+    clearStmt;
+    removeStmt;
+    searchStmt;
+    replaceTxn;
+    constructor(dbPath) {
+        this.db = new better_sqlite3_1.default(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, entries) => {
+                this.clearStmt.run(key);
+                for (const entry of entries)
+                    this.appendStmt.run(key, JSON.stringify(entry), (0, memory_1.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, entry) {
+        this.appendStmt.run(key, JSON.stringify(entry), (0, memory_1.searchableText)(entry));
+    }
+    async read(key) {
+        const rows = this.readStmt.all(key);
+        return rows.map((row) => JSON.parse(row.entry));
+    }
+    async clear(key) {
+        this.clearStmt.run(key);
+    }
+    async replace(key, entries) {
+        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, ids) {
+        if (ids.length === 0)
+            return;
+        this.removeStmt.run(key, JSON.stringify(ids));
+    }
+    async search(key, query, opts = {}) {
+        const terms = (0, memory_1.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, (0, memory_1.clampSearchLimit)(opts.limit));
+        return rows.map((row) => JSON.parse(row.entry));
+    }
+    async close() {
+        this.db.close();
+    }
+}
+exports.SqliteMemoryStore = SqliteMemoryStore;
+//# sourceMappingURL=SqliteMemoryStore.js.map

package/dist/SqliteMemoryStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteMemoryStore.js","sourceRoot":"","sources":["../src/SqliteMemoryStore.ts"],"names":[],"mappings":"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"}

package/dist/SqliteReadModelStore.d.ts

@@ -0,0 +1,38 @@
+import type { FoldedApply, FoldedApplyResult, FoldedRecord, FoldedSelector, ReadModelPage, ReadModelQuery, ReadModelRow, ReadModelScalar, ReadModelStore } from "@loomwork/plugin-read-model";
+/**
+ * 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 declare class SqliteReadModelStore implements ReadModelStore {
+    private readonly db;
+    private readonly insertRowStmt;
+    private readonly upsertMarkStmt;
+    private readonly watermarkStmt;
+    private readonly watermarkedStmt;
+    private readonly clearRowsStmt;
+    private readonly clearMarksStmt;
+    private readonly foldHeaderStmt;
+    private readonly upsertFoldHeaderStmt;
+    private readonly dropFoldStatesStmt;
+    private readonly dropFoldHeaderStmt;
+    private readonly applyFoldedStmt;
+    constructor(dbPath: string);
+    apply(modelId: string, executionId: string, upToSequence: number, rows: readonly ReadModelRow[]): Promise<void>;
+    watermark(modelId: string, executionId: string): Promise<number | null>;
+    watermarkedExecutions(modelId: string): Promise<string[]>;
+    query(modelId: string, q?: ReadModelQuery): Promise<ReadModelPage>;
+    purge(modelId: string, where: Record<string, ReadModelScalar>): Promise<number>;
+    clear(modelId: string): Promise<void>;
+    beginFold(modelId: string, foldVersion: string): Promise<{
+        rebuilt: boolean;
+    }>;
+    applyFolded(a: FoldedApply): Promise<FoldedApplyResult>;
+    getFolded(modelId: string, executionIds: readonly string[]): Promise<FoldedRecord[]>;
+    getFoldedByKey(modelId: string, keys: readonly string[]): Promise<FoldedRecord[]>;
+    purgeFolded(modelId: string, selector: FoldedSelector): Promise<number>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=SqliteReadModelStore.d.ts.map

package/dist/SqliteReadModelStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteReadModelStore.d.ts","sourceRoot":"","sources":["../src/SqliteReadModelStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,eAAe,EACf,cAAc,EACf,MAAM,6BAA6B,CAAC;AAyCrC;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;IAGvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqB;IAC1D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;gBAEzC,MAAM,EAAE,MAAM;IA6FpB,KAAK,CACT,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,YAAY,EAAE,GAC5B,OAAO,CAAC,IAAI,CAAC;IAkBV,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKvE,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKzD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAuDtE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB/E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAarC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAc9E,WAAW,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqBvD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiBpF,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAgBjF,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAavE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/SqliteReadModelStore.js

@@ -0,0 +1,292 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteReadModelStore = void 0;
+const plugin_read_model_1 = require("@loomwork/plugin-read-model");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+function toFolded(r) {
+    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).
+ */
+class SqliteReadModelStore {
+    db;
+    // Audit fix (DS&A rank 2): statements are prepared ONCE — apply-heavy
+    // catch-ups no longer re-parse identical SQL per call.
+    insertRowStmt;
+    upsertMarkStmt;
+    watermarkStmt;
+    watermarkedStmt;
+    clearRowsStmt;
+    clearMarksStmt;
+    foldHeaderStmt;
+    upsertFoldHeaderStmt;
+    dropFoldStatesStmt;
+    dropFoldHeaderStmt;
+    applyFoldedStmt;
+    constructor(dbPath) {
+        this.db = new better_sqlite3_1.default(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, executionId, upToSequence, rows) {
+        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, executionId) {
+        const row = this.watermarkStmt.get(modelId, executionId);
+        return row?.sequence ?? null;
+    }
+    async watermarkedExecutions(modelId) {
+        const rows = this.watermarkedStmt.all(modelId);
+        return rows.map((r) => r.execution_id);
+    }
+    async query(modelId, q = {}) {
+        const desc = q.order === "desc";
+        const limit = (0, plugin_read_model_1.clampQueryLimit)(q.limit);
+        const clauses = ["model_id = ?"];
+        const params = [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] = (0, plugin_read_model_1.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);
+        const page = records.slice(0, limit).map((r) => ({
+            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, where) {
+        (0, plugin_read_model_1.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 = [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) {
+        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, foldVersion) {
+        // 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);
+            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) {
+        // IMMEDIATE for the same reason: the miss path reads the header after the write attempt.
+        return this.db
+            .transaction(() => {
+            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);
+            if (hit !== undefined)
+                return hit.erased === 1 ? "applied-erased" : "applied";
+            const hdr = this.foldHeaderStmt.get(a.modelId);
+            return hdr?.version === a.foldVersion ? "stale" : "version-mismatch";
+        })
+            .immediate();
+    }
+    async getFolded(modelId, executionIds) {
+        (0, plugin_read_model_1.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);
+        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, keys) {
+        (0, plugin_read_model_1.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);
+        return rows.map(toFolded);
+    }
+    async purgeFolded(modelId, selector) {
+        (0, plugin_read_model_1.assertFoldedSelector)(selector);
+        const [col, val] = (0, plugin_read_model_1.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() {
+        this.db.close();
+    }
+}
+exports.SqliteReadModelStore = SqliteReadModelStore;
+//# sourceMappingURL=SqliteReadModelStore.js.map

package/dist/SqliteReadModelStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteReadModelStore.js","sourceRoot":"","sources":["../src/SqliteReadModelStore.ts"],"names":[],"mappings":"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"}

package/dist/SqliteSnapshotStore.d.ts

@@ -0,0 +1,31 @@
+import { type Snapshot, type SnapshotCodecName, type SnapshotStore } from "@loomwork/snapshot-runtime";
+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;
+}
+export declare class SqliteSnapshotStore implements SnapshotStore {
+    private readonly db;
+    /** ADR 0141 - the codec new snapshots are written with (structural; `ProfilingSnapshotStore` reads it). */
+    readonly snapshotCodec: SnapshotCodecName;
+    constructor(dbPath: string, options?: SqliteSnapshotStoreOptions);
+    save(snapshot: Snapshot): Promise<void>;
+    loadLatest(executionId: string): Promise<Snapshot | null>;
+    loadAt(executionId: string, sequence: number): Promise<Snapshot | null>;
+    loadLatestBefore(executionId: string, sequence: number): Promise<Snapshot | null>;
+    deleteExecution(executionId: string): Promise<void>;
+    listSequences(executionId: string, range?: {
+        readonly after?: number;
+        readonly before?: number;
+    }): Promise<number[]>;
+    pruneSnapshots(executionId: string, range: {
+        readonly after: number;
+        readonly before: number;
+    }, keep?: readonly number[]): Promise<number>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=SqliteSnapshotStore.d.ts.map

package/dist/SqliteSnapshotStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteSnapshotStore.d.ts","sourceRoot":"","sources":["../src/SqliteSnapshotStore.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAKnB,MAAM,4BAA4B,CAAC;AAepC,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAeD,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;IACvC,2GAA2G;IAC3G,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B;IAc9D,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IASzD,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IASvE,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IASjF,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChE,OAAO,CAAC,MAAM,EAAE,CAAC;IAoBd,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC1D,IAAI,GAAE,SAAS,MAAM,EAAO,GAC3B,OAAO,CAAC,MAAM,CAAC;IAWZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/SqliteSnapshotStore.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteSnapshotStore = void 0;
+const snapshot_runtime_1 = require("@loomwork/snapshot-runtime");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const snapshotSchema_1 = require("./snapshotSchema");
+function rowToSnapshot(row) {
+    return {
+        id: row.id,
+        executionId: row.execution_id,
+        workflowId: row.workflow_id,
+        sequence: row.sequence,
+        state: (typeof row.state === "string"
+            ? JSON.parse(row.state)
+            : (0, snapshot_runtime_1.decodeState)(row.state)),
+        createdAt: row.created_at,
+    };
+}
+class SqliteSnapshotStore {
+    db;
+    /** ADR 0141 - the codec new snapshots are written with (structural; `ProfilingSnapshotStore` reads it). */
+    snapshotCodec;
+    constructor(dbPath, options = {}) {
+        this.snapshotCodec = (0, snapshot_runtime_1.parseSnapshotCodec)(options.codec);
+        (0, snapshot_runtime_1.assertSnapshotCodecAvailable)(this.snapshotCodec);
+        this.db = new better_sqlite3_1.default(dbPath);
+        try {
+            this.db.pragma("journal_mode = WAL");
+            this.db.pragma("synchronous = NORMAL");
+            (0, snapshotSchema_1.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) {
+        this.db
+            .prepare(`
+        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)
+            : (0, snapshot_runtime_1.encodeState)(snapshot.state, this.snapshotCodec), snapshot.createdAt);
+    }
+    async loadLatest(executionId) {
+        const row = this.db
+            .prepare("SELECT * FROM snapshots WHERE execution_id = ? ORDER BY sequence DESC LIMIT 1")
+            .get(executionId);
+        return row ? rowToSnapshot(row) : null;
+    }
+    async loadAt(executionId, sequence) {
+        const row = this.db
+            .prepare("SELECT * FROM snapshots WHERE execution_id = ? AND sequence = ?")
+            .get(executionId, sequence);
+        return row ? rowToSnapshot(row) : null;
+    }
+    async loadLatestBefore(executionId, sequence) {
+        const row = this.db
+            .prepare("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) {
+        this.db.prepare("DELETE FROM snapshots WHERE execution_id = ?").run(executionId);
+    }
+    async listSequences(executionId, range = {}) {
+        // 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 = [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(`SELECT sequence FROM snapshots WHERE ${where.join(" AND ")} ORDER BY sequence`)
+            .all(...args);
+        return rows.map((r) => r.sequence);
+    }
+    async pruneSnapshots(executionId, range, keep = []) {
+        // One statement. The keep-set is a bound JSON array, not an interpolated list.
+        const info = this.db
+            .prepare(`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() {
+        this.db.close();
+    }
+}
+exports.SqliteSnapshotStore = SqliteSnapshotStore;
+//# sourceMappingURL=SqliteSnapshotStore.js.map