purra-sqlite 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# purra-sqlite · TypeScript
+
+English | [简体中文](README.zh-CN.md)
+
+SQLite persistence for PurrA Runs, events, operations, budgets, checkpoints, and
+tool receipts. Requires Node.js 22.13+ for `node:sqlite`.
+
+## Install
+
+Follow [source installation](../../README.md#source-installation), selecting
+`integrations/sqlite/typescript`.
+
+## Configure
+
+Given a configured model gateway `model`:
+
+```ts
+import { Agent } from "purra";
+import { SqliteAgentAdapters } from "purra-sqlite";
+
+const storage = new SqliteAgentAdapters("agent.db", {
+  scope: "user-1/project-1",
+});
+const agent = new Agent({
+  model,
+  runRepository: storage.runs,
+  outputPublisher: storage.publisher,
+  idempotency: storage.idempotency,
+});
+```
+
+Select `scope` from the application's authenticated user/project binding.
+The bundle also exposes `runTree`, `artifacts`, and `longTasks`.
+
+## Recovery
+
+`agent.resume(runId, originalRequest)` restores an eligible checkpoint with its
+existing budget and deadline. Restore the original model and tool configuration.
+The repository supplies execution ownership to prevent concurrent resumes.
+
+For uncertain external tool writes, call
+`storage.reconcileTool(key, { result })` or
+`storage.reconcileTool(key, { notExecuted: true })` only after confirming what
+happened. For persisted questions and answers, use
+[SqliteClarification](../../interaction/typescript/README.md).
+
+## Storage and shutdown
+
+Canonical output events are appended as rows with Run and Root sequence indexes.
+Event additions and the execution snapshot commit in one transaction.
+`runs.listEvents()`, `runs.listRootEvents()` and subscription polling neither load
+the execution snapshot nor acquire a writer lock. `runs.get()` remains read-only.
+Tool receipts and lease renewal/release skip Run state and journal hydration;
+Agent tree, Artifact and Long Task operations restore only their own repository.
+Writes targeting an existing Run validate sequence counts in SQL, use indexed
+source-key lookups and buffer only new events. Core planning, public-progress
+and terminal-settlement rules read original Run evidence on demand. Persisted
+counts and pending events jointly determine Run and Root sequences; sibling
+budgets remain shared. Run reads restore the complete Root journal. Unloaded Roots reject access;
+their checkpoints and event counts are preserved. Lease acquisition, public
+`transaction()` and operations such as creating a Run still validate the full
+scope. Execution snapshots retain checkpoints and receipts and
+are still loaded and saved at scope granularity. This adapter therefore
+still suits bounded local workloads.
+Storage v3 rejects v1/v2 data without automatic migration; existing databases
+cannot be resumed directly.
+Python and TypeScript execution snapshots are not interchangeable.
+The source-key index is local to each Root (Python keys are scope-wide).
+Opening existing v3 data creates the index using SQLite `json_extract`.
+Sequence checks scan a covering index for the selected Root and match each child
+by Run id, without fetching event body rows. Root headers have a covering index
+as well. Existing v3 databases build these indexes on opening, consuming time and
+disk space; inserts maintain the extra indexes. Metadata remains scope-sized;
+writes are not constant-cost. Event bodies are validated when read. Lease
+acquisition and public transactions retain full journal hydration.
+
+After building Core and this package, run the empty-poll and tail-pagination
+benchmark from the repository root:
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-reads.mjs
+```
+
+This temporary-database benchmark reports warm median read latency, not
+concurrent throughput or real-model end-to-end performance.
+
+Measure tool receipt writes, including claim and result-commit transactions:
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-writes.mjs
+```
+
+The tool callback is local and has no external side effect; this excludes real
+business-tool and model latency.
+
+Measure active Run event writes beside a growing unrelated Root:
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-run-writes.mjs
+```
+
+This measures isolation from other Roots, not scaling within a single growing Root.
+
+Measure appends, invocation registration and checkpoint commits within the same
+growing Root (two warmups and ten measured writes per operation):
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-execution-writes.mjs
+```
+
+History consists of private diagnostic events. Results exclude planning evidence
+replay, concurrent throughput and real Provider latency. Unlike Python's
+reservation and checkpoint APIs, TypeScript emits an output event for each of
+these operations, so compare each SDK against its own baseline.
+Add `--profile` to report journal preparation, Run state import/export and the
+remaining transaction time. The remainder includes outer snapshot handling,
+other repositories and SQL writes. Phase medians are calculated independently
+and need not sum to the total median.
+
+The application owns database access, backups, and retention. Checkpoints contain
+private model data. Wait for active executions to settle before `storage.close()`.

package/README.zh-CN.md

@@ -0,0 +1,104 @@
+# purra-sqlite · TypeScript
+
+[English](README.md) | 简体中文
+
+为 PurrA 的 Run、事件、操作、预算、检查点和工具回执提供 SQLite 持久化。
+依赖 `node:sqlite`，要求 Node.js 22.13+。
+
+## 安装
+
+按照[源码安装说明](../../README.zh-CN.md#从源码安装)操作，选择
+`integrations/sqlite/typescript`。
+
+## 配置
+
+已有模型网关 `model` 时：
+
+```ts
+import { Agent } from "purra";
+import { SqliteAgentAdapters } from "purra-sqlite";
+
+const storage = new SqliteAgentAdapters("agent.db", {
+  scope: "user-1/project-1",
+});
+const agent = new Agent({
+  model,
+  runRepository: storage.runs,
+  outputPublisher: storage.publisher,
+  idempotency: storage.idempotency,
+});
+```
+
+`scope` 应由应用根据已认证的用户与项目绑定确定。
+该组件还提供 `runTree`、`artifacts` 和 `longTasks`。
+
+## 恢复
+
+`agent.resume(runId, originalRequest)` 恢复满足条件的检查点，并保留原有预算和截止时间。
+恢复时还原原有模型与工具配置。仓储提供执行所有权控制，阻止并发恢复。
+
+外部工具写入结果不确定时，先确认实际执行情况，再调用
+`storage.reconcileTool(key, { result })` 或
+`storage.reconcileTool(key, { notExecuted: true })`。
+需要保存提问和回答时，使用 [SqliteClarification](../../interaction/typescript/README.zh-CN.md)。
+
+## 存储与关闭
+
+规范输出事件按行增量保存，通过 Run 序号和 Root 序号索引分页读取。事件追加与执行状态
+快照在同一个事务中提交；`runs.listEvents()`、`runs.listRootEvents()` 和订阅轮询不加载
+执行快照，也不申请写锁。`runs.get()` 保持只读事务。工具回执、租约续期与释放跳过
+Run 状态和输出历史的还原；Agent 树、产物与长任务操作只还原对应仓储。
+指向已有 Run 的写入先通过 SQL 校验序号和事件数量，按索引查询幂等键，并缓冲新增事件。
+规划、公开进度和终态收尾所需的原始证据仍由 Core 按需读取。已持久化的事件数量和
+待提交事件共同决定 Run 与 Root 的序号，兄弟任务仍共享预算。Run 读取完整还原所属
+Root 日志；未加载的 Root 不能读取或写入，其检查点与事件计数保持不变。
+租约认领、公开 `transaction()` 和创建 Run 等无法定位既有 Root 的操作仍校验完整作用域。
+执行快照仍按作用域加载和保存，包含检查点和回执，适合数据量受控的本地场景。
+本次存储格式为 v3，明确拒绝 v1/v2 数据；没有自动迁移，已有数据库不能直接恢复。
+Python 与 TypeScript 的执行快照不能互换。
+事件幂等键的索引范围是单个 Root（Python 则是整个作用域）。打开已有 v3 数据库时，
+通过 SQLite `json_extract` 建立该索引。序号校验使用选定 Root 的覆盖索引，并按 Run
+精确匹配子任务，无需读取事件正文所在的数据行。Root 与 Run 的映射也有覆盖索引。
+已有 v3 数据库在打开时补建索引，需要耗时和额外磁盘，新增事件也需要维护索引。
+元数据仍按作用域保存，
+因此写入成本并非常数。事件正文在读取时校验；租约认领和公开事务仍还原完整日志。
+
+构建 Core 和本包后，在仓库根目录运行空轮询与末尾分页基准：
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-reads.mjs
+```
+
+基准使用临时数据库，报告预热后的读取中位耗时，不代表并发吞吐量或真实模型端到端性能。
+
+工具回执写入基准计入认领和结果提交两个事务，使用本地无外部副作用的工具函数：
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-writes.mjs
+```
+
+它不计真实业务工具或模型调用耗时。
+
+另一个 Root 的历史数据增长时，活动 Run 的事件写入成本可用以下基准测量：
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-run-writes.mjs
+```
+
+它测量无关 Root 的隔离效果，不代表活动 Root 自身历史不断增长时的性能。
+
+同一 Root 内的事件追加、调用登记和检查点提交基准，每种操作预热两次后测量十次：
+
+```sh
+node integrations/sqlite/typescript/scripts/benchmark-execution-writes.mjs
+```
+
+历史数据为私有诊断事件；结果不包含规划证据重放、并发吞吐量或真实 Provider 耗时。
+与 Python 的调用登记和检查点接口不同，TypeScript 的这两类操作都会追加输出事件，
+因此应分别与各 SDK 自身的基线比较。
+追加 `--profile` 可分别查看日志准备、Run 状态导入导出和事务其余部分的耗时。
+其余部分包含外层快照处理、其他仓储和 SQL 写入。各分段的中位数独立计算，
+不能直接相加得到总耗时中位数。
+
+应用负责数据库访问、备份和数据保留。检查点包含私有模型数据。
+等待活动执行结束后再调用 `storage.close()`。

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { InMemoryRunRepository, InMemoryRunTreeRepository, InMemoryArtifactStore, InMemoryLongTaskRepository, type OutputPublisher, type ToolHandlerResult, type ToolIdempotencyGateway } from "purra";
+declare function stores(): {
+    runs: InMemoryRunRepository;
+    runTree: InMemoryRunTreeRepository;
+    artifacts: InMemoryArtifactStore;
+    longTasks: InMemoryLongTaskRepository;
+};
+type Stores = ReturnType<typeof stores>;
+export declare class SqliteAgentAdapters {
+    #private;
+    readonly runs: InMemoryRunRepository;
+    readonly runTree: InMemoryRunTreeRepository;
+    readonly artifacts: InMemoryArtifactStore;
+    readonly artifactClaims: InMemoryArtifactStore;
+    readonly artifactMaintenance: InMemoryArtifactStore;
+    readonly longTasks: InMemoryLongTaskRepository;
+    readonly publisher: OutputPublisher;
+    readonly idempotency: ToolIdempotencyGateway;
+    constructor(path: string, options: {
+        scope: string;
+    });
+    transaction<T>(operation: (all: Stores, extra: {
+        tools: Record<string, any>;
+        [key: string]: any;
+    }) => Promise<T>): Promise<T>;
+    reconcileTool(key: string, proof: {
+        result: ToolHandlerResult;
+    } | {
+        notExecuted: true;
+    }): Promise<void>;
+    close(): void;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,240 @@
+import { OutputJournal, STORAGE_VERSION } from "./journal.js";
+import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { openSync, closeSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import { InMemoryRunRepository, InMemoryRunTreeRepository, InMemoryArtifactStore, InMemoryLongTaskRepository, } from "purra";
+function stores() {
+    const runTree = new InMemoryRunTreeRepository();
+    const runs = new InMemoryRunRepository({ leaseValidator: (id, claim) => runTree.requireRunClaim(id, claim) });
+    return { runs, runTree, artifacts: new InMemoryArtifactStore(), longTasks: new InMemoryLongTaskRepository() };
+}
+const RUN_READ_METHODS = new Set(["get", "listEvents", "listRootEvents"]);
+const ROOT_BOUND_METHODS = new Set(["get", "openInvocation", "appendEvent", "appendBatch", "saveExecutionCheckpoint", "settleInvocation", "settleRun", "cancel"]);
+export class SqliteAgentAdapters {
+    #db;
+    #scope;
+    #journal;
+    #tail = Promise.resolve();
+    #active = false;
+    #owner = new AsyncLocalStorage();
+    runs = this.#port("runs");
+    runTree = this.#port("runTree");
+    artifacts = this.#port("artifacts");
+    artifactClaims = this.artifacts;
+    artifactMaintenance = this.artifacts;
+    longTasks = this.#port("longTasks");
+    publisher = {
+        publishCommitted: async (event) => {
+            const rows = await this.runs.listEvents(event.runId, event.sequence - 1, 1);
+            if (JSON.stringify(rows[0]) !== JSON.stringify(event))
+                throw new Error("only persisted output can be published");
+        },
+        waitForSequence: async (id, after, signal) => {
+            while (!(await this.runs.listEvents(id, after, 1)).length)
+                await sleep(50, undefined, { signal });
+        },
+    };
+    idempotency = {
+        executeOnce: async (key, operation) => {
+            const saved = await this.#extraTransaction(async (extra) => {
+                if (extra.tools[key]) {
+                    if (extra.tools[key].state === "claimed")
+                        throw new Error("tool_effect_unknown");
+                    return extra.tools[key].result;
+                }
+                extra.tools[key] = { state: "claimed" };
+                return undefined;
+            });
+            if (saved !== undefined)
+                return saved;
+            const result = await operation();
+            await this.#extraTransaction(async (extra) => { extra.tools[key] = { state: "complete", result }; });
+            return result;
+        },
+    };
+    constructor(path, options) {
+        if (!options.scope.trim())
+            throw new TypeError("scope is required");
+        this.#scope = options.scope;
+        if (path !== ":memory:") {
+            try {
+                closeSync(openSync(path, "ax", 0o600));
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        this.#db = new DatabaseSync(path);
+        this.#db.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=0; PRAGMA foreign_keys=ON;");
+        this.#db.exec("CREATE TABLE IF NOT EXISTS purra_state (scope TEXT NOT NULL, sdk TEXT NOT NULL, version INTEGER NOT NULL, body TEXT NOT NULL, PRIMARY KEY(scope,sdk))");
+        this.#journal = new OutputJournal(this.#db, this.#scope);
+    }
+    #port(name) {
+        const methods = new Set(Object.getOwnPropertyNames(Object.getPrototypeOf(stores()[name])));
+        return new Proxy({}, { get: (_target, method) => {
+                if (name === "runs" && method === "executeOwned")
+                    return this.#executeOwned.bind(this);
+                if (name === "runs" && (method === "listEvents" || method === "listRootEvents")) {
+                    return (id, after, limit) => this.#withConnection(async () => this.#journal.read(id, after, limit, method === "listRootEvents"), true);
+                }
+                if (!methods.has(method) || method === "constructor")
+                    return undefined;
+                return (...args) => this.#transaction(async (all, extra) => {
+                    if (name === "runs" && !["get", "listEvents", "listRootEvents"].includes(method)) {
+                        const lease = extra.leases[String(args[0])];
+                        const owner = this.#owner.getStore();
+                        if (owner !== undefined && lease && (lease.owner !== owner || lease.expires <= Date.now()))
+                            throw new Error("run_lease_lost");
+                    }
+                    return all[name][method](...args);
+                }, name === "runs" && RUN_READ_METHODS.has(method), name === "runs" ? "all" : name, name === "runs" && ROOT_BOUND_METHODS.has(method) && typeof args[0] === "string" ? args[0] : undefined);
+            } });
+    }
+    async #executeOwned(runId, operation, checkpoint) {
+        const owner = globalThis.crypto.randomUUID();
+        await this.transaction(async (all, extra) => {
+            const saved = await all.runs.get(runId);
+            if (saved.status !== "running")
+                throw new Error("run_terminal");
+            const old = extra.leases[runId];
+            if (old && old.owner !== null && old.expires > Date.now())
+                throw new Error("run_lease_conflict");
+            if (checkpoint !== undefined && JSON.stringify(saved.executionCheckpoint) !== JSON.stringify(checkpoint))
+                throw new Error("checkpoint_conflict");
+            if (checkpoint !== undefined) {
+                const events = await all.runs.listEvents(runId, 0, Number.MAX_SAFE_INTEGER);
+                const lastCheckpoint = events.reduce((last, event, index) => event.kind === "agent.execution_checkpoint" ? index : last, -1);
+                if (events.slice(lastCheckpoint + 1).some(event => event.kind === "invocation.started"))
+                    throw new Error("run_recovery_requires_reconciliation");
+            }
+            extra.leases[runId] = { owner, expires: Date.now() + 30000 };
+        });
+        let stopped = false;
+        const heartbeat = async () => {
+            while (!stopped) {
+                await sleep(1000, undefined, { signal: stop.signal }).catch(() => { });
+                if (stopped)
+                    break;
+                await this.#extraTransaction(async (extra) => {
+                    if (extra.leases[runId]?.owner !== owner)
+                        throw new Error("run_lease_lost");
+                    extra.leases[runId].expires = Date.now() + 30000;
+                });
+            }
+        };
+        const stop = new AbortController();
+        let heartbeatError;
+        const monitor = heartbeat().catch((error) => { heartbeatError = error; });
+        try {
+            const result = await this.#owner.run(owner, operation);
+            if (heartbeatError)
+                throw heartbeatError;
+            return result;
+        }
+        finally {
+            stopped = true;
+            stop.abort();
+            await monitor;
+            await this.#extraTransaction(async (extra) => {
+                if (extra.leases[runId]?.owner === owner)
+                    extra.leases[runId] = { owner: null, expires: 0 };
+            });
+        }
+    }
+    async transaction(operation) {
+        return this.#transaction(operation);
+    }
+    async #withConnection(operation, readOnly = false) {
+        const previous = this.#tail;
+        let release;
+        this.#tail = new Promise((resolve) => { release = resolve; });
+        await previous;
+        this.#active = true;
+        let begun = false;
+        try {
+            const deadline = Date.now() + 5000;
+            for (;;) {
+                try {
+                    this.#db.exec(readOnly ? "BEGIN" : "BEGIN IMMEDIATE");
+                    begun = true;
+                    break;
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || !error.message.includes("locked") || Date.now() >= deadline)
+                        throw error;
+                    await sleep(10);
+                }
+            }
+            const result = await operation();
+            this.#db.exec("COMMIT");
+            begun = false;
+            return result;
+        }
+        catch (error) {
+            if (begun)
+                this.#db.exec("ROLLBACK");
+            throw error;
+        }
+        finally {
+            this.#active = false;
+            release();
+        }
+    }
+    async #extraTransaction(operation) {
+        return this.#transaction(async (_all, extra) => operation(extra), false, "extra");
+    }
+    async #transaction(operation, readOnly = false, selection = "all", journalRunId) {
+        return this.#withConnection(async () => {
+            const all = stores();
+            const row = this.#db.prepare("SELECT version,body FROM purra_state WHERE scope=? AND sdk='typescript'").get(this.#scope);
+            if (row && row.version !== STORAGE_VERSION)
+                throw new Error("unsupported SQLite storage version");
+            const saved = row ? JSON.parse(String(row.body)) : { extra: { tools: Object.create(null) } };
+            saved.extra.tools = Object.assign(Object.create(null), saved.extra.tools);
+            saved.extra.leases = Object.assign(Object.create(null), saved.extra.leases);
+            const rootRunId = row && journalRunId !== undefined ? this.#journal.rootForRun(journalRunId) : undefined;
+            const deferredJournal = row && selection === "all" && !readOnly && rootRunId !== undefined ? this.#journal.deferred(rootRunId) : undefined;
+            const events = row && selection === "all" && deferredJournal === undefined ? this.#journal.restore(rootRunId) : [];
+            const prior = new Map(deferredJournal?.counts);
+            for (const event of events)
+                prior.set(event.runId, event.sequence);
+            if (saved.runs && selection === "all")
+                all.runs.importState(saved.runs, deferredJournal === undefined ? events : undefined, { ...(rootRunId === undefined ? {} : { rootRunId }), ...(deferredJournal === undefined ? {} : { deferredJournal }) });
+            for (const key of ["runTree", "artifacts", "longTasks"])
+                if (saved[key] && (selection === "all" || selection === key))
+                    all[key].importState(saved[key]);
+            const result = await operation(all, saved.extra);
+            if (!readOnly) {
+                const checkpoint = selection === "all" ? all.runs.exportJournalState({ incremental: true }) : undefined;
+                if (checkpoint !== undefined)
+                    saved.runs = checkpoint.state;
+                for (const key of ["runTree", "artifacts", "longTasks"]) {
+                    if (selection === "all" || selection === key)
+                        saved[key] = all[key].exportState();
+                }
+                const body = JSON.stringify(saved);
+                if (!row || row.body !== body)
+                    this.#db.prepare("INSERT INTO purra_state VALUES(?, 'typescript', 3, ?) ON CONFLICT(scope,sdk) DO UPDATE SET version=excluded.version,body=excluded.body").run(this.#scope, body);
+                if (checkpoint !== undefined)
+                    this.#journal.append(checkpoint.journals, prior);
+            }
+            return result;
+        }, readOnly);
+    }
+    async reconcileTool(key, proof) {
+        await this.#extraTransaction(async (extra) => {
+            if (extra.tools[key]?.state !== "claimed")
+                throw new Error("tool_claim_conflict");
+            if ("result" in proof)
+                extra.tools[key] = { state: "complete", result: proof.result };
+            else if (proof.notExecuted === true)
+                delete extra.tools[key];
+            else
+                throw new TypeError("invalid tool reconciliation proof");
+        });
+    }
+    close() { if (this.#active)
+        throw new Error("storage transaction is active"); this.#db.close(); }
+}

package/dist/journal.d.ts

@@ -0,0 +1,24 @@
+import type { DatabaseSync } from "node:sqlite";
+import { type OutputEvent } from "purra";
+export declare const STORAGE_VERSION = 3;
+export declare class OutputJournal {
+    private readonly db;
+    private readonly scope;
+    constructor(db: DatabaseSync, scope: string);
+    rootForRun(runId: string): string | undefined;
+    restore(rootRunId?: string): readonly OutputEvent[];
+    deferred(rootRunId: string): {
+        counts: Map<string, number>;
+        readRun: (runId: string) => readonly OutputEvent[];
+        readRoot: () => readonly OutputEvent[];
+        findSource: (key: string) => OutputEvent | undefined;
+    };
+    restoreRun(runId: string): readonly OutputEvent[];
+    append(journals: readonly {
+        readonly runId: string;
+        readonly rootRunId: string;
+        readonly afterSequence?: number;
+        readonly events: readonly OutputEvent[];
+    }[], prior: ReadonlyMap<string, number>): void;
+    read(runId: string, after: number, limit?: number, root?: boolean): readonly OutputEvent[];
+}

package/dist/journal.js

@@ -0,0 +1,124 @@
+import { AgentError } from "purra";
+export const STORAGE_VERSION = 3;
+function decode(text) {
+    const freeze = (value) => {
+        if (value !== null && typeof value === "object") {
+            for (const child of Object.values(value))
+                freeze(child);
+            Object.freeze(value);
+        }
+        return value;
+    };
+    return freeze(JSON.parse(text));
+}
+function decodeRow(row) {
+    const event = decode(String(row.body));
+    if (event.runId !== row.run_id || event.rootRunId !== row.root_run_id
+        || event.sequence !== row.sequence || event.rootSequence !== row.root_sequence) {
+        throw new TypeError("invalid output journal identity or sequence");
+    }
+    return event;
+}
+export class OutputJournal {
+    db;
+    scope;
+    constructor(db, scope) {
+        this.db = db;
+        this.scope = scope;
+        db.exec(`CREATE TABLE IF NOT EXISTS purra_journal_runs (
+      scope TEXT NOT NULL, sdk TEXT NOT NULL, run_id TEXT NOT NULL,
+      root_run_id TEXT NOT NULL, PRIMARY KEY(scope,sdk,run_id),
+      FOREIGN KEY(scope,sdk) REFERENCES purra_state(scope,sdk) ON DELETE CASCADE);
+      CREATE TABLE IF NOT EXISTS purra_output_events (
+      scope TEXT NOT NULL, sdk TEXT NOT NULL, run_id TEXT NOT NULL,
+      sequence INTEGER NOT NULL, root_run_id TEXT NOT NULL,
+      root_sequence INTEGER NOT NULL, body TEXT NOT NULL,
+      PRIMARY KEY(scope,sdk,run_id,sequence),
+      UNIQUE(scope,sdk,root_run_id,root_sequence),
+      FOREIGN KEY(scope,sdk,run_id) REFERENCES purra_journal_runs(scope,sdk,run_id) ON DELETE CASCADE);
+      CREATE UNIQUE INDEX IF NOT EXISTS purra_typescript_output_source
+      ON purra_output_events(scope,root_run_id,json_extract(body,'$.sourceKey')) WHERE sdk='typescript';
+      CREATE INDEX IF NOT EXISTS purra_output_sequence_cover
+      ON purra_output_events(scope,sdk,root_run_id,run_id,sequence,root_sequence);
+      CREATE INDEX IF NOT EXISTS purra_journal_roots
+      ON purra_journal_runs(scope,sdk,root_run_id,run_id);`);
+    }
+    rootForRun(runId) {
+        const row = this.db.prepare("SELECT root_run_id FROM purra_journal_runs WHERE scope=? AND sdk='typescript' AND run_id=?").get(this.scope, runId);
+        return row === undefined ? undefined : String(row.root_run_id);
+    }
+    restore(rootRunId) {
+        const query = this.db.prepare("SELECT body FROM purra_output_events WHERE scope=? AND sdk='typescript'"
+            + (rootRunId === undefined ? "" : " AND root_run_id=?") + " ORDER BY root_run_id,root_sequence");
+        const rows = rootRunId === undefined ? query.all(this.scope) : query.all(this.scope, rootRunId);
+        return rows.map((row) => decode(String(row.body)));
+    }
+    deferred(rootRunId) {
+        const rows = this.db.prepare(`SELECT r.run_id,COUNT(e.sequence) AS count,
+      MIN(e.sequence) AS first,MAX(e.sequence) AS last,
+      MIN(e.root_sequence) AS root_first,MAX(e.root_sequence) AS root_last
+      FROM purra_journal_runs r LEFT JOIN purra_output_events e
+      ON e.scope=r.scope AND e.sdk=r.sdk AND e.run_id=r.run_id AND e.root_run_id=r.root_run_id
+      WHERE r.scope=? AND r.sdk='typescript' AND r.root_run_id=? GROUP BY r.run_id`).all(this.scope, rootRunId);
+        const counts = new Map();
+        let rootFirst = Infinity, rootLast = 0, total = 0;
+        for (const row of rows) {
+            const count = Number(row.count);
+            if (count && (row.first !== 1 || row.last !== count))
+                throw new TypeError("invalid output journal sequence");
+            counts.set(String(row.run_id), count);
+            total += count;
+            if (count) {
+                rootFirst = Math.min(rootFirst, Number(row.root_first));
+                rootLast = Math.max(rootLast, Number(row.root_last));
+            }
+        }
+        if (total && (rootFirst !== 1 || rootLast !== total))
+            throw new TypeError("incomplete output journal");
+        return {
+            counts,
+            readRun: (runId) => this.restoreRun(runId),
+            readRoot: () => this.restore(rootRunId),
+            findSource: (key) => {
+                const row = this.db.prepare("SELECT run_id,root_run_id,sequence,root_sequence,body FROM purra_output_events WHERE scope=? AND sdk='typescript' AND root_run_id=? AND json_extract(body,'$.sourceKey')=?").get(this.scope, rootRunId, key);
+                return row === undefined ? undefined : decodeRow(row);
+            },
+        };
+    }
+    restoreRun(runId) {
+        return this.db.prepare("SELECT run_id,root_run_id,sequence,root_sequence,body FROM purra_output_events WHERE scope=? AND sdk='typescript' AND run_id=? ORDER BY sequence")
+            .all(this.scope, runId).map(decodeRow);
+    }
+    append(journals, prior) {
+        const insertRun = this.db.prepare("INSERT INTO purra_journal_runs VALUES (?, 'typescript', ?, ?)");
+        const insertEvent = this.db.prepare("INSERT INTO purra_output_events VALUES (?, 'typescript', ?, ?, ?, ?, ?)");
+        for (const journal of journals) {
+            if (!prior.has(journal.runId))
+                insertRun.run(this.scope, journal.runId, journal.rootRunId);
+            const offset = journal.afterSequence ?? 0;
+            const count = prior.get(journal.runId) ?? 0;
+            if (offset > count)
+                throw new TypeError("output journal append has a gap");
+            for (const event of journal.events.slice(count - offset)) {
+                insertEvent.run(this.scope, event.runId, event.sequence, event.rootRunId, event.rootSequence, JSON.stringify(event));
+            }
+        }
+    }
+    read(runId, after, limit = 200, root = false) {
+        const row = this.db.prepare("SELECT version FROM purra_state WHERE scope=? AND sdk='typescript'").get(this.scope);
+        if (row && row.version !== STORAGE_VERSION)
+            throw new Error("unsupported SQLite storage version");
+        const run = row && this.db.prepare("SELECT root_run_id FROM purra_journal_runs WHERE scope=? AND sdk='typescript' AND run_id=?").get(this.scope, runId);
+        if (!run)
+            throw new AgentError("run_not_found", "Run does not exist");
+        if (root && run.root_run_id !== runId)
+            throw new AgentError("run_scope_conflict", "Root journal query requires a Root Run");
+        if (!Number.isSafeInteger(after) || after < 0)
+            throw new TypeError(`${root ? "afterRootSequence" : "afterSequence"} must be a non-negative integer`);
+        if (!Number.isSafeInteger(limit) || limit < 1)
+            throw new TypeError("limit must be positive");
+        const [identity, sequence] = root ? ["root_run_id", "root_sequence"] : ["run_id", "sequence"];
+        const rows = this.db.prepare(`SELECT body FROM purra_output_events WHERE scope=? AND sdk='typescript' AND ${identity}=? AND ${sequence}>? ORDER BY ${sequence} LIMIT ?`).all(this.scope, runId, after, limit);
+        return Object.freeze(rows.map((item) => decode(String(item.body))));
+    }
+}

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "purra-sqlite", "version": "0.5.0", "type": "module", "license": "MIT",
+  "description": "SQLite persistence for PurrA",
+  "engines": { "node": ">=22.13.0" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "peerDependencies": { "purra": "0.5.0" },
+  "devDependencies": { "@types/node": "22.20.1", "purra": "file:../../../typescript", "typescript": "7.0.2" },
+  "scripts": { "build": "tsc -p tsconfig.json", "test": "node --test test/*.test.mjs", "check": "npm run build && npm test", "prepack": "npm run build" }
+}