@m4ike1/ion-session-backend-sqlite-node 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-24
+
+### Breaking Changes
+
+- Restarted the `@m4ike1` version line at 0.1.0. The versions inherited from upstream Pi (`0.85.1`, `0.86.1`) stay on npm and remain installable by exact version, but they are a different line: this release sorts below them, so an existing `^0.86.1` range will not pick it up, and inter-package ranges move to `^0.1.0`. The `latest` dist-tag follows ion's own line from this release onward.
+
+## [0.86.1] - 2026-09-24
+
+## [0.86.0] - 2026-09-24
+
+### Breaking Changes
+
+- Renamed product `pi` → `ion` (breaking). Package names `@m4ike1/pi-*` → `@m4ike1/ion-*` (`ionConfig` instead of `piConfig`, `@m4ike1/ion-coding-agent`, `@m4ike1/ion-ai`, etc.), binary `pi` → `ion`, config directory `.pi` → `.ion` (XDG now immediate at `~/.config/ion`, `~/.local/share/ion`, `~/.local/state/ion`, `~/.cache/ion`), environment variables `PI_*` → `ION_*` (`PI_CODING_AGENT_DIR` → `ION_CODING_AGENT_DIR`, `PI_DISABLE_SESSION_INDEX` etc., with `PI_*` fallback for one release), and `pi.dev` → `ion.dev`. Legacy `~/.pi` is migrated on first run if `~/.config/ion` is missing. `APP_TITLE` `π` → `⛬`.
+- Renamed this package from `@maikel/ion-session-backend-sqlite-node` to `@m4ike1/ion-session-backend-sqlite-node` (breaking). The `@maikel` npm scope belongs to another account, so the fork publishes under `@m4ike1`. Import specifiers and dependency ranges change accordingly. Nothing was ever published under the old scope, so there is no published version to migrate from.
+
+
+
+## [0.85.1] - 2026-09-05
+
+## [0.85.0] - 2026-09-04
+
+## [0.84.4] - 2026-08-28
+
+## [0.84.3] - 2026-08-24
+
+## [0.84.2] - 2026-08-14
+
+## [0.84.1] - 2026-08-07
+
+### Added
+
+- Added the composable, parameterized `sql` template tag for SQLite queries.
+
+### Fixed
+
+- Fixed SQLite branch queries to apply filters, cursors, and limits in SQL; bounded log reads; and added covering indexes for session, record, branch, and fact queries ([#7727](https://github.com/maikel/pi/pull/7727) by [@cristinaponcela](https://github.com/cristinaponcela)).
+
+## [0.84.0] - 2026-08-06
+
+### Breaking Changes
+
+- Renamed the package from `@m4ike1/pi-storage-sqlite-node` to `@m4ike1/pi-session-backend-sqlite-node`.
+- Replaced the legacy SQLite session schema and repository with the v4 lane-based `SessionRepo` contract. Existing work-in-progress databases are not migrated.
+
+### Added
+
+- Added bounded active-branch queries, durable operation records, global facts, shared sequence allocation, session statistics, and fenced writer leases to the SQLite backend.
+
+### Fixed
+
+- Fixed SQLite session listings to avoid acquiring writer claims and include current session names, allowing inventory reads while sessions have active writers ([#7655](https://github.com/maikel/pi/pull/7655)).
+
+## [0.83.0] - 2026-07-29
+
+## [0.82.1] - 2026-07-25
+
+## [0.82.0] - 2026-07-24
+
+## [0.81.1] - 2026-07-21
+
+## [0.81.0] - 2026-07-21
+
+### Added
+
+- Added a Node.js SQLite storage backend for agent harness sessions, including migrations and materialized session views ([#6594](https://github.com/maikel/pi/pull/6594) by [@cristinaponcela](https://github.com/cristinaponcela)).

package/README.md

@@ -0,0 +1,62 @@
+# @m4ike1/ion-session-backend-sqlite-node
+
+SQLite session storage backend for `@m4ike1/ion-agent-core`, built on `node:sqlite` (`node >= 22.19`).
+
+```ts
+import { BACKGROUND_CONTEXT } from "@m4ike1/ion-agent-core";
+import {
+  createNodeSqliteFactory,
+  SqliteSessionRepo,
+} from "@m4ike1/ion-session-backend-sqlite-node";
+
+const repository = new SqliteSessionRepo({
+  directory: "/var/lib/ion/sessions",
+  databaseFactory: createNodeSqliteFactory(),
+});
+
+const session = await repository.create({}, BACKGROUND_CONTEXT);
+const main = await session.createBranch("main", null, BACKGROUND_CONTEXT);
+await main.appendMessage(
+  { role: "user", content: "hello", timestamp: Date.now() },
+  BACKGROUND_CONTEXT,
+);
+await session.close(BACKGROUND_CONTEXT);
+await repository.close(BACKGROUND_CONTEXT);
+```
+
+## Layout
+
+- Default: one file per session under `directory`. Safe IDs (`[A-Za-z0-9_-]+`)
+  map to `{sessionId}.sqlite`; all other IDs use a `~`-prefixed base64url
+  encoding of the UTF-16LE bytes. The durable session ID is unchanged;
+  `metadata.path` carries the canonical physical path.
+- `databasePath` option: store multiple sessions in one shared container.
+  Its parent directory is created on demand.
+
+## Lifecycle and ownership
+
+- `open()` and `delete()` reject metadata whose path is outside the
+  configured repository, and never create a missing database.
+- `list()` is read-only and best-effort: corrupt files, version mismatches,
+  and unrelated `*.sqlite` files are skipped.
+- One writable owner per session is the host's responsibility. The repo
+  rejects overlapping local create/open/fork/delete for one ID but provides
+  no cross-process lease, lock, fence, heartbeat, or takeover. Close a worker
+  before deletion.
+- `fork()` of a source open in the same repo queues its snapshot on that
+  source's commit queue. Any other source uses an independent read-only
+  connection with one deferred WAL transaction; later worker commits may land
+  while the snapshot is open. Forks copy entries and scalar/list values, not
+  usage ledger rows.
+- `repository.close()` waits for every open session cleanup attempt before
+  reporting errors (single error rethrown, multiple aggregated).
+- No search service or FTS index is exported; search is a separate projection.
+
+## Further reading
+
+- [Setup and tasks](docs/setup.md) — layout choice, open/list/delete/fork
+  recipes, custom factories, shutdown order.
+- [Reference](docs/reference.md) — public API: repo, sessions, factory,
+  database capability, `sql` helper, constants.
+- [Concepts](docs/concepts.md) — file layout and ID encoding, ownership
+  model, fork snapshots, version gate, schema.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { DatabaseSync } from "node:sqlite";
+import type { SqliteDatabase, SqliteDatabaseFactory } from "./sqlite/types.ts";
+export declare function wrapNodeSqliteDatabase(db: DatabaseSync): SqliteDatabase;
+export declare function createNodeSqliteFactory(): SqliteDatabaseFactory;
+export * from "./sqlite/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAoC,MAAM,mBAAmB,CAAC;AAiGjH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,YAAY,GAAG,cAAc,CAEvE;AAED,wBAAgB,uBAAuB,IAAI,qBAAqB,CAc/D;AAGD,cAAc,mBAAmB,CAAC","sourcesContent":["import type { SQLInputValue } from \"node:sqlite\";\nimport { DatabaseSync } from \"node:sqlite\";\nimport { pathToFileURL } from \"node:url\";\nimport { sql } from \"./sqlite/sql.ts\";\nimport type { SqliteDatabase, SqliteDatabaseFactory, SqliteRunResult, SqliteStatement } from \"./sqlite/types.ts\";\n\nfunction isNamedParameters(value: unknown): value is Record<string, SQLInputValue> {\n\tif (value === null || typeof value !== \"object\") return false;\n\tif (Array.isArray(value) || ArrayBuffer.isView(value)) return false;\n\treturn true;\n}\n\nfunction isAsyncResult(value: unknown): boolean {\n\treturn value !== null && (typeof value === \"object\" || typeof value === \"function\") && \"then\" in value;\n}\n\nclass NodeSqliteStatement implements SqliteStatement {\n\tprivate readonly statement: ReturnType<DatabaseSync[\"prepare\"]>;\n\n\tconstructor(statement: ReturnType<DatabaseSync[\"prepare\"]>) {\n\t\tthis.statement = statement;\n\t}\n\n\trun(...params: unknown[]): SqliteRunResult {\n\t\tconst [first, ...rest] = params;\n\t\tconst result = isNamedParameters(first)\n\t\t\t? this.statement.run(first, ...(rest as SQLInputValue[]))\n\t\t\t: this.statement.run(...(params as SQLInputValue[]));\n\t\treturn {\n\t\t\tchanges: Number(result.changes),\n\t\t\tlastInsertRowid: result.lastInsertRowid === undefined ? undefined : Number(result.lastInsertRowid),\n\t\t};\n\t}\n\n\tget<TRow extends object>(...params: unknown[]): TRow | undefined {\n\t\tconst [first, ...rest] = params;\n\t\treturn (\n\t\t\tisNamedParameters(first)\n\t\t\t\t? this.statement.get(first, ...(rest as SQLInputValue[]))\n\t\t\t\t: this.statement.get(...(params as SQLInputValue[]))\n\t\t) as TRow | undefined;\n\t}\n\n\tall<TRow extends object>(...params: unknown[]): TRow[] {\n\t\tconst [first, ...rest] = params;\n\t\treturn (\n\t\t\tisNamedParameters(first)\n\t\t\t\t? this.statement.all(first, ...(rest as SQLInputValue[]))\n\t\t\t\t: this.statement.all(...(params as SQLInputValue[]))\n\t\t) as TRow[];\n\t}\n\n\titerate<TRow extends object>(...params: unknown[]): Iterable<TRow> {\n\t\tconst [first, ...rest] = params;\n\t\treturn (\n\t\t\tisNamedParameters(first)\n\t\t\t\t? this.statement.iterate(first, ...(rest as SQLInputValue[]))\n\t\t\t\t: this.statement.iterate(...(params as SQLInputValue[]))\n\t\t) as Iterable<TRow>;\n\t}\n}\n\nclass NodeSqliteDatabase implements SqliteDatabase {\n\tprivate readonly db: DatabaseSync;\n\n\tconstructor(db: DatabaseSync) {\n\t\tthis.db = db;\n\t}\n\n\texec(sql: string): void {\n\t\tthis.db.exec(sql);\n\t}\n\n\tprepare(sql: string): SqliteStatement {\n\t\treturn new NodeSqliteStatement(this.db.prepare(sql));\n\t}\n\n\ttransaction<T>(fn: () => T): T {\n\t\tsql`BEGIN IMMEDIATE`.exec(this);\n\t\ttry {\n\t\t\tconst result = fn();\n\t\t\tif (isAsyncResult(result)) {\n\t\t\t\tthrow new TypeError(\"SQLite transaction callbacks must be synchronous\");\n\t\t\t}\n\t\t\tsql`COMMIT`.exec(this);\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tsql`ROLLBACK`.exec(this);\n\t\t\t} catch {\n\t\t\t\t// Ignore rollback errors to rethrow original error.\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tclose(): void {\n\t\tthis.db.close();\n\t}\n}\n\nexport function wrapNodeSqliteDatabase(db: DatabaseSync): SqliteDatabase {\n\treturn new NodeSqliteDatabase(db);\n}\n\nexport function createNodeSqliteFactory(): SqliteDatabaseFactory {\n\treturn {\n\t\tasync open(path: string): Promise<SqliteDatabase> {\n\t\t\treturn new NodeSqliteDatabase(new DatabaseSync(path));\n\t\t},\n\t\tasync openExisting(path: string): Promise<SqliteDatabase> {\n\t\t\tconst url = pathToFileURL(path);\n\t\t\turl.searchParams.set(\"mode\", \"rw\");\n\t\t\treturn new NodeSqliteDatabase(new DatabaseSync(url));\n\t\t},\n\t\tasync openReadOnly(path: string): Promise<SqliteDatabase> {\n\t\t\treturn new NodeSqliteDatabase(new DatabaseSync(path, { readOnly: true }));\n\t\t},\n\t};\n}\n\n// Re-export the SQLite session backend and types so this package is a complete node-sqlite backend.\nexport * from \"./sqlite/index.ts\";\n"]}

package/dist/index.js

@@ -0,0 +1,103 @@
+import { DatabaseSync } from "node:sqlite";
+import { pathToFileURL } from "node:url";
+import { sql } from "./sqlite/sql.js";
+function isNamedParameters(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value) || ArrayBuffer.isView(value))
+        return false;
+    return true;
+}
+function isAsyncResult(value) {
+    return value !== null && (typeof value === "object" || typeof value === "function") && "then" in value;
+}
+class NodeSqliteStatement {
+    statement;
+    constructor(statement) {
+        this.statement = statement;
+    }
+    run(...params) {
+        const [first, ...rest] = params;
+        const result = isNamedParameters(first)
+            ? this.statement.run(first, ...rest)
+            : this.statement.run(...params);
+        return {
+            changes: Number(result.changes),
+            lastInsertRowid: result.lastInsertRowid === undefined ? undefined : Number(result.lastInsertRowid),
+        };
+    }
+    get(...params) {
+        const [first, ...rest] = params;
+        return (isNamedParameters(first)
+            ? this.statement.get(first, ...rest)
+            : this.statement.get(...params));
+    }
+    all(...params) {
+        const [first, ...rest] = params;
+        return (isNamedParameters(first)
+            ? this.statement.all(first, ...rest)
+            : this.statement.all(...params));
+    }
+    iterate(...params) {
+        const [first, ...rest] = params;
+        return (isNamedParameters(first)
+            ? this.statement.iterate(first, ...rest)
+            : this.statement.iterate(...params));
+    }
+}
+class NodeSqliteDatabase {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    prepare(sql) {
+        return new NodeSqliteStatement(this.db.prepare(sql));
+    }
+    transaction(fn) {
+        sql `BEGIN IMMEDIATE`.exec(this);
+        try {
+            const result = fn();
+            if (isAsyncResult(result)) {
+                throw new TypeError("SQLite transaction callbacks must be synchronous");
+            }
+            sql `COMMIT`.exec(this);
+            return result;
+        }
+        catch (error) {
+            try {
+                sql `ROLLBACK`.exec(this);
+            }
+            catch {
+                // Ignore rollback errors to rethrow original error.
+            }
+            throw error;
+        }
+    }
+    close() {
+        this.db.close();
+    }
+}
+export function wrapNodeSqliteDatabase(db) {
+    return new NodeSqliteDatabase(db);
+}
+export function createNodeSqliteFactory() {
+    return {
+        async open(path) {
+            return new NodeSqliteDatabase(new DatabaseSync(path));
+        },
+        async openExisting(path) {
+            const url = pathToFileURL(path);
+            url.searchParams.set("mode", "rw");
+            return new NodeSqliteDatabase(new DatabaseSync(url));
+        },
+        async openReadOnly(path) {
+            return new NodeSqliteDatabase(new DatabaseSync(path, { readOnly: true }));
+        },
+    };
+}
+// Re-export the SQLite session backend and types so this package is a complete node-sqlite backend.
+export * from "./sqlite/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SQLInputValue } from \"node:sqlite\";\nimport { DatabaseSync } from \"node:sqlite\";\nimport { pathToFileURL } from \"node:url\";\nimport { sql } from \"./sqlite/sql.ts\";\nimport type { SqliteDatabase, SqliteDatabaseFactory, SqliteRunResult, SqliteStatement } from \"./sqlite/types.ts\";\n\nfunction isNamedParameters(value: unknown): value is Record<string, SQLInputValue> {\n\tif (value === null || typeof value !== \"object\") return false;\n\tif (Array.isArray(value) || ArrayBuffer.isView(value)) return false;\n\treturn true;\n}\n\nfunction isAsyncResult(value: unknown): boolean {\n\treturn value !== null && (typeof value === \"object\" || typeof value === \"function\") && \"then\" in value;\n}\n\nclass NodeSqliteStatement implements SqliteStatement {\n\tprivate readonly statement: ReturnType<DatabaseSync[\"prepare\"]>;\n\n\tconstructor(statement: ReturnType<DatabaseSync[\"prepare\"]>) {\n\t\tthis.statement = statement;\n\t}\n\n\trun(...params: unknown[]): SqliteRunResult {\n\t\tconst [first, ...rest] = params;\n\t\tconst result = isNamedParameters(first)\n\t\t\t? this.statement.run(first, ...(rest as SQLInputValue[]))\n\t\t\t: this.statement.run(...(params as SQLInputValue[]));\n\t\treturn {\n\t\t\tchanges: Number(result.changes),\n\t\t\tlastInsertRowid: result.lastInsertRowid === undefined ? undefined : Number(result.lastInsertRowid),\n\t\t};\n\t}\n\n\tget<TRow extends object>(...params: unknown[]): TRow | undefined {\n\t\tconst [first, ...rest] = params;\n\t\treturn (\n\t\t\tisNamedParameters(first)\n\t\t\t\t? this.statement.get(first, ...(rest as SQLInputValue[]))\n\t\t\t\t: this.statement.get(...(params as SQLInputValue[]))\n\t\t) as TRow | undefined;\n\t}\n\n\tall<TRow extends object>(...params: unknown[]): TRow[] {\n\t\tconst [first, ...rest] = params;\n\t\treturn (\n\t\t\tisNamedParameters(first)\n\t\t\t\t? this.statement.all(first, ...(rest as SQLInputValue[]))\n\t\t\t\t: this.statement.all(...(params as SQLInputValue[]))\n\t\t) as TRow[];\n\t}\n\n\titerate<TRow extends object>(...params: unknown[]): Iterable<TRow> {\n\t\tconst [first, ...rest] = params;\n\t\treturn (\n\t\t\tisNamedParameters(first)\n\t\t\t\t? this.statement.iterate(first, ...(rest as SQLInputValue[]))\n\t\t\t\t: this.statement.iterate(...(params as SQLInputValue[]))\n\t\t) as Iterable<TRow>;\n\t}\n}\n\nclass NodeSqliteDatabase implements SqliteDatabase {\n\tprivate readonly db: DatabaseSync;\n\n\tconstructor(db: DatabaseSync) {\n\t\tthis.db = db;\n\t}\n\n\texec(sql: string): void {\n\t\tthis.db.exec(sql);\n\t}\n\n\tprepare(sql: string): SqliteStatement {\n\t\treturn new NodeSqliteStatement(this.db.prepare(sql));\n\t}\n\n\ttransaction<T>(fn: () => T): T {\n\t\tsql`BEGIN IMMEDIATE`.exec(this);\n\t\ttry {\n\t\t\tconst result = fn();\n\t\t\tif (isAsyncResult(result)) {\n\t\t\t\tthrow new TypeError(\"SQLite transaction callbacks must be synchronous\");\n\t\t\t}\n\t\t\tsql`COMMIT`.exec(this);\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tsql`ROLLBACK`.exec(this);\n\t\t\t} catch {\n\t\t\t\t// Ignore rollback errors to rethrow original error.\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tclose(): void {\n\t\tthis.db.close();\n\t}\n}\n\nexport function wrapNodeSqliteDatabase(db: DatabaseSync): SqliteDatabase {\n\treturn new NodeSqliteDatabase(db);\n}\n\nexport function createNodeSqliteFactory(): SqliteDatabaseFactory {\n\treturn {\n\t\tasync open(path: string): Promise<SqliteDatabase> {\n\t\t\treturn new NodeSqliteDatabase(new DatabaseSync(path));\n\t\t},\n\t\tasync openExisting(path: string): Promise<SqliteDatabase> {\n\t\t\tconst url = pathToFileURL(path);\n\t\t\turl.searchParams.set(\"mode\", \"rw\");\n\t\t\treturn new NodeSqliteDatabase(new DatabaseSync(url));\n\t\t},\n\t\tasync openReadOnly(path: string): Promise<SqliteDatabase> {\n\t\t\treturn new NodeSqliteDatabase(new DatabaseSync(path, { readOnly: true }));\n\t\t},\n\t};\n}\n\n// Re-export the SQLite session backend and types so this package is a complete node-sqlite backend.\nexport * from \"./sqlite/index.ts\";\n"]}

package/dist/sqlite/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./repo.ts";
+export * from "./sql.ts";
+export * from "./storage.ts";
+export type { SqliteDatabase, SqliteDatabaseFactory, SqliteRunResult, SqliteStatement, } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/sqlite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sqlite/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,YAAY,EACX,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,eAAe,GACf,MAAM,YAAY,CAAC","sourcesContent":["export * from \"./repo.ts\";\nexport * from \"./sql.ts\";\nexport * from \"./storage.ts\";\nexport type {\n\tSqliteDatabase,\n\tSqliteDatabaseFactory,\n\tSqliteRunResult,\n\tSqliteStatement,\n} from \"./types.ts\";\n"]}

package/dist/sqlite/index.js

@@ -0,0 +1,4 @@
+export * from "./repo.js";
+export * from "./sql.js";
+export * from "./storage.js";
+//# sourceMappingURL=index.js.map

package/dist/sqlite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sqlite/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC","sourcesContent":["export * from \"./repo.ts\";\nexport * from \"./sql.ts\";\nexport * from \"./storage.ts\";\nexport type {\n\tSqliteDatabase,\n\tSqliteDatabaseFactory,\n\tSqliteRunResult,\n\tSqliteStatement,\n} from \"./types.ts\";\n"]}

package/dist/sqlite/migrations/001_initial.sql

@@ -0,0 +1,121 @@
+-- AgentHarness storage format 4 / storageVersion 1.
+-- A SQLite database file is a session container. The current default repo
+-- placement still creates one file per session, but the schema supports any
+-- number of sessions per file by scoping every durable row with session_id.
+-- Authoritative durable state is entries + scalar_values + list_values +
+-- usage_ledger; branch_* and stats columns on sessions are maintained
+-- projections/caches.
+
+CREATE TABLE IF NOT EXISTS sessions (
+	id TEXT PRIMARY KEY,
+	created_at INTEGER NOT NULL,
+	parent_session_id TEXT,
+	storage_version INTEGER NOT NULL,
+	metadata TEXT,
+	message_count INTEGER NOT NULL,
+	usage_payload TEXT NOT NULL,
+	next_seq INTEGER NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS entries (
+	session_id TEXT NOT NULL,
+	id TEXT NOT NULL,
+	parent_id TEXT,
+	seq INTEGER NOT NULL,
+	type TEXT NOT NULL,
+	custom_type TEXT,
+	timestamp INTEGER NOT NULL,
+	payload TEXT NOT NULL,
+	PRIMARY KEY (session_id, id)
+) WITHOUT ROWID;
+
+CREATE INDEX IF NOT EXISTS ix_entry_parent ON entries(session_id, parent_id);
+CREATE INDEX IF NOT EXISTS ix_entry_seq ON entries(session_id, seq, type);
+
+CREATE TABLE IF NOT EXISTS scalar_values (
+	session_id TEXT NOT NULL,
+	namespace TEXT NOT NULL,
+	key TEXT NOT NULL,
+	seq INTEGER NOT NULL,
+	value TEXT NOT NULL,
+	PRIMARY KEY (session_id, namespace, key)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS list_values (
+	session_id TEXT NOT NULL,
+	namespace TEXT NOT NULL,
+	key TEXT NOT NULL,
+	seq INTEGER NOT NULL,
+	value TEXT NOT NULL,
+	PRIMARY KEY (session_id, namespace, key, seq)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS usage_ledger (
+	session_id TEXT NOT NULL,
+	id TEXT NOT NULL,
+	seq INTEGER NOT NULL,
+	entry_id TEXT,
+	adjustment INTEGER NOT NULL,
+	usage TEXT NOT NULL,
+	details TEXT,
+	PRIMARY KEY (session_id, id)
+) WITHOUT ROWID;
+
+CREATE INDEX IF NOT EXISTS ix_usage_seq ON usage_ledger(session_id, seq);
+
+-- Storage-level integrity that spans rows/tables. Primary keys enforce
+-- same-table duplicate ids; these triggers enforce the shared entry/usage id
+-- namespace and ordered parent insertion without a TypeScript preflight pass.
+CREATE TRIGGER IF NOT EXISTS trg_entries_validate
+BEFORE INSERT ON entries
+BEGIN
+	SELECT RAISE(ABORT, 'missing parent entry')
+	WHERE NEW.parent_id IS NOT NULL
+		AND NOT EXISTS (
+			SELECT 1 FROM entries WHERE session_id = NEW.session_id AND id = NEW.parent_id
+		);
+
+	SELECT RAISE(ABORT, 'duplicate entry or usage id')
+	WHERE EXISTS (
+		SELECT 1 FROM usage_ledger WHERE session_id = NEW.session_id AND id = NEW.id
+	);
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_usage_ledger_validate
+BEFORE INSERT ON usage_ledger
+BEGIN
+	SELECT RAISE(ABORT, 'duplicate entry or usage id')
+	WHERE EXISTS (
+		SELECT 1 FROM entries WHERE session_id = NEW.session_id AND id = NEW.id
+	);
+END;
+
+-- Private branch index. Not values/lists; no equivalent in the other backends.
+CREATE TABLE IF NOT EXISTS branch_entries (
+	session_id TEXT NOT NULL,
+	branch_id TEXT NOT NULL,
+	entry_id TEXT NOT NULL,
+	entry_seq INTEGER NOT NULL,
+	entry_type TEXT NOT NULL,
+	PRIMARY KEY (session_id, branch_id, entry_id)
+) WITHOUT ROWID;
+
+-- Ordered scans. entry_seq must follow session_id, branch_id directly or ORDER
+-- BY needs a temp b-tree; entry_id and entry_type trail so the index covers
+-- id-only reads.
+CREATE INDEX IF NOT EXISTS ix_be_seq ON branch_entries(session_id, branch_id, entry_seq, entry_id, entry_type);
+-- Type-filtered scans.
+CREATE INDEX IF NOT EXISTS ix_be_type ON branch_entries(session_id, branch_id, entry_type, entry_seq, entry_id);
+CREATE INDEX IF NOT EXISTS ix_be_entry ON branch_entries(session_id, entry_id);
+
+CREATE TABLE IF NOT EXISTS branch_meta (
+	session_id TEXT NOT NULL,
+	branch_id TEXT NOT NULL,
+	tip_entry_id TEXT NOT NULL,
+	tip_seq INTEGER NOT NULL,
+	base_branch_id TEXT,
+	base_seq INTEGER,
+	PRIMARY KEY (session_id, branch_id)
+) WITHOUT ROWID;
+
+CREATE UNIQUE INDEX IF NOT EXISTS ix_bm_tip ON branch_meta(session_id, tip_entry_id);

package/dist/sqlite/migrations.d.ts

@@ -0,0 +1,3 @@
+import type { SqliteDatabase } from "./types.ts";
+export declare function applyInitialSchema(db: SqliteDatabase): Promise<void>;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/sqlite/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/sqlite/migrations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { fileURLToPath } from \"node:url\";\nimport type { SqliteDatabase } from \"./types.ts\";\n\nexport async function applyInitialSchema(db: SqliteDatabase): Promise<void> {\n\tconst migration = await readFile(fileURLToPath(new URL(\"./migrations/001_initial.sql\", import.meta.url)), \"utf8\");\n\tdb.exec(migration);\n}\n"]}

package/dist/sqlite/migrations.js

@@ -0,0 +1,7 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+export async function applyInitialSchema(db) {
+    const migration = await readFile(fileURLToPath(new URL("./migrations/001_initial.sql", import.meta.url)), "utf8");
+    db.exec(migration);
+}
+//# sourceMappingURL=migrations.js.map

package/dist/sqlite/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/sqlite/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAkB,EAAiB;IAC3E,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,8BAA8B,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAClH,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAAA,CACnB","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { fileURLToPath } from \"node:url\";\nimport type { SqliteDatabase } from \"./types.ts\";\n\nexport async function applyInitialSchema(db: SqliteDatabase): Promise<void> {\n\tconst migration = await readFile(fileURLToPath(new URL(\"./migrations/001_initial.sql\", import.meta.url)), \"utf8\");\n\tdb.exec(migration);\n}\n"]}

package/dist/sqlite/repo.d.ts

@@ -0,0 +1,41 @@
+import type { Context, ForkOptions, SessionCreateOptions } from "@m4ike1/ion-agent-core";
+import { type SqliteSessionMetadata } from "./session/session-row.ts";
+import { SqliteOpenSession } from "./session.ts";
+import type { SqliteDatabaseFactory } from "./types.ts";
+export declare const SQLITE_STORAGE_VERSION = 1;
+export declare const SQLITE_SESSION_EXTENSION = ".sqlite";
+export type SqliteSessionCreateOptions = SessionCreateOptions;
+export interface SqliteSessionRepoOptions {
+    directory: string;
+    /** Optional single container path. Defaults to one encoded `${id}.sqlite` file per session under directory. */
+    databasePath?: string;
+    databaseFactory: SqliteDatabaseFactory;
+    now?: () => number;
+}
+export declare class SqliteSessionRepo {
+    private readonly directory;
+    private readonly databasePath;
+    private readonly databaseFactory;
+    private readonly now;
+    private readonly pendingIds;
+    private readonly openStorages;
+    private readonly openSessions;
+    private closed;
+    private closePromise;
+    constructor(options: SqliteSessionRepoOptions);
+    create(options: SqliteSessionCreateOptions | undefined, _context: Context): Promise<SqliteOpenSession>;
+    open(metadata: SqliteSessionMetadata, _context: Context): Promise<SqliteOpenSession>;
+    list(_options: undefined, _context: Context): Promise<SqliteSessionMetadata[]>;
+    delete(metadata: SqliteSessionMetadata, _context: Context): Promise<void>;
+    fork(source: SqliteSessionMetadata, options: ForkOptions, context: Context): Promise<SqliteOpenSession>;
+    close(context: Context): Promise<void>;
+    private createForkSnapshotFromExternalSource;
+    private closeOpenSessions;
+    private openStorageBackedSession;
+    private repositoryPathForMetadata;
+    private reserveId;
+    private pathForSession;
+    private usesSharedDatabase;
+    private assertOpen;
+}
+//# sourceMappingURL=repo.d.ts.map

package/dist/sqlite/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/sqlite/repo.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAS,WAAW,EAAE,oBAAoB,EAAe,MAAM,wBAAwB,CAAC;AAM7G,OAAO,EAON,KAAK,qBAAqB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAKlD,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,CAAC;AAE9D,MAAM,WAAW,wBAAwB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,qBAAqB,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAuHD,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IACjE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgC;IAC7D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA4B;IAEhD,YAAY,OAAO,EAAE,wBAAwB,EAK5C;IAEK,MAAM,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiD3G;IAEK,IAAI,CAAC,QAAQ,EAAE,qBAAqB,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsBzF;IAEK,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAmCnF;IAEK,MAAM,CAAC,QAAQ,EAAE,qBAAqB,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E;IAEK,IAAI,CAAC,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgE5G;IAED,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrC;YAEa,oCAAoC;YAcpC,iBAAiB;IAO/B,OAAO,CAAC,wBAAwB;YAoBlB,yBAAyB;IAWvC,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,UAAU;CAGlB","sourcesContent":["import { mkdir, open as openFile, readdir, realpath, rm } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport type { Context, Entry, ForkOptions, SessionCreateOptions, StoredValue } from \"@m4ike1/ion-agent-core\";\nimport { branchTip, createForkSnapshot, StorageBackedSession } from \"@m4ike1/ion-agent-core\";\nimport { uuidv7 } from \"@m4ike1/ion-ai\";\nimport { applyInitialSchema } from \"./migrations.ts\";\nimport { appendEntryToBranchIndex, scanBranchEntries } from \"./session/branch-entries.ts\";\nimport { decodeEntryRow, type EntryRow, EntryRowWriter } from \"./session/entries.ts\";\nimport {\n\tdeleteSessionRows,\n\thasSessionRow,\n\tinsertSessionRow,\n\tmetadataFromSessionRow,\n\treadAllSessionRows,\n\treadSessionRow,\n\ttype SqliteSessionMetadata,\n} from \"./session/session-row.ts\";\nimport { readAllScalarValueRows, setScalarValueRow } from \"./session/values.ts\";\nimport { SqliteOpenSession } from \"./session.ts\";\nimport { sql } from \"./sql.ts\";\nimport { SqliteStorage, type SqliteStorageSnapshot } from \"./storage.ts\";\nimport type { SqliteDatabase, SqliteDatabaseFactory } from \"./types.ts\";\n\nexport const SQLITE_STORAGE_VERSION = 1;\nexport const SQLITE_SESSION_EXTENSION = \".sqlite\";\n\nconst FIRST_AVAILABLE_COMMIT_SEQ = 1;\nconst SAFE_SESSION_FILE_ID = /^[A-Za-z0-9_-]+$/;\n\nexport type SqliteSessionCreateOptions = SessionCreateOptions;\n\nexport interface SqliteSessionRepoOptions {\n\tdirectory: string;\n\t/** Optional single container path. Defaults to one encoded `${id}.sqlite` file per session under directory. */\n\tdatabasePath?: string;\n\tdatabaseFactory: SqliteDatabaseFactory;\n\tnow?: () => number;\n}\n\nfunction sessionFileName(id: string): string {\n\tif (SAFE_SESSION_FILE_ID.test(id)) return `${id}${SQLITE_SESSION_EXTENSION}`;\n\tconst encoded = Buffer.from(id, \"utf16le\").toString(\"base64url\");\n\treturn `~${encoded}${SQLITE_SESSION_EXTENSION}`;\n}\n\nfunction sessionPath(directory: string, id: string): string {\n\treturn join(directory, sessionFileName(id));\n}\n\nfunction storageIdentity(path: string, sessionId: string): string {\n\treturn JSON.stringify([path, sessionId]);\n}\n\nfunction isErrorWithCode(error: unknown, code: string): boolean {\n\treturn typeof error === \"object\" && error !== null && \"code\" in error && error.code === code;\n}\n\nasync function removeSessionFiles(path: string, options: { force: boolean }): Promise<void> {\n\tawait rm(path, { force: options.force });\n\tawait rm(`${path}-wal`, { force: true });\n\tawait rm(`${path}-shm`, { force: true });\n}\n\nfunction configureWritableConnection(db: SqliteDatabase): void {\n\tdb.exec(\"PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;\");\n}\n\nfunction configureReadOnlyConnection(db: SqliteDatabase): void {\n\tdb.exec(\"PRAGMA busy_timeout = 5000;\");\n}\n\ninterface ForkSnapshot {\n\tentries: Entry[];\n\tscalarValues: StoredValue<unknown>[];\n\tmessageCount: number;\n\tnextSeq: number;\n}\n\nfunction readSourceEntries(db: SqliteDatabase, sessionId: string): Entry[] {\n\treturn sql`SELECT id, parent_id, seq, type, custom_type, timestamp, payload\n\t\tFROM entries WHERE session_id = ${sessionId} ORDER BY seq ASC`\n\t\t.all<EntryRow>(db)\n\t\t.map(decodeEntryRow);\n}\n\nfunction buildForkSnapshot(source: SqliteStorageSnapshot, options: ForkOptions): ForkSnapshot {\n\tconst snapshot = createForkSnapshot(\n\t\t{\n\t\t\tentries: source.entries,\n\t\t\tscalarValues: source.scalarValues,\n\t\t\tentriesComplete: source.entriesComplete,\n\t\t},\n\t\toptions,\n\t);\n\tconst entries = [...snapshot.entries.values()].sort((left, right) => left.seq - right.seq);\n\treturn {\n\t\tentries,\n\t\tscalarValues: snapshot.scalarValues,\n\t\tmessageCount: entries.filter((entry) => entry.type === \"message\").length,\n\t\tnextSeq: snapshot.nextSeq,\n\t};\n}\n\n// TODO(WP08): Remove this snapshot path when SQLite forks use streaming staging.\nfunction readForkSourceEntries(\n\tdb: SqliteDatabase,\n\tsessionId: string,\n\tscalarValues: readonly StoredValue<unknown>[],\n\toptions: ForkOptions,\n): Entry[] {\n\tif (options.scope === \"tree\") return readSourceEntries(db, sessionId);\n\tconst sourceAddress = branchTip(options.branch);\n\tconst sourceTip = scalarValues.find(\n\t\t(stored) => stored.address.namespace === sourceAddress.namespace && stored.address.key === sourceAddress.key,\n\t) as StoredValue<string | null> | undefined;\n\tif (sourceTip === undefined) throw new Error(`Unknown source branch: ${options.branch}`);\n\treturn sourceTip.value === null\n\t\t? []\n\t\t: scanBranchEntries(db, sessionId, { start: sourceTip.value, order: \"oldestFirst\" });\n}\n\nfunction createSqliteForkSnapshot(\n\tsourceDb: SqliteDatabase,\n\tsource: SqliteSessionMetadata,\n\toptions: ForkOptions,\n): ForkSnapshot {\n\tsourceDb.exec(\"BEGIN\");\n\tlet committed = false;\n\ttry {\n\t\tmetadataFromSessionRow(source.path, readSessionRow(sourceDb, source.id), SQLITE_STORAGE_VERSION);\n\t\tconst scalarValues = readAllScalarValueRows(sourceDb, source.id);\n\t\tconst snapshot = buildForkSnapshot(\n\t\t\t{\n\t\t\t\tentries: readForkSourceEntries(sourceDb, source.id, scalarValues, options),\n\t\t\t\tscalarValues,\n\t\t\t\tentriesComplete: options.scope === \"tree\",\n\t\t\t},\n\t\t\toptions,\n\t\t);\n\t\tsourceDb.exec(\"COMMIT\");\n\t\tcommitted = true;\n\t\treturn snapshot;\n\t} catch (error) {\n\t\tif (!committed) sourceDb.exec(\"ROLLBACK\");\n\t\tthrow error;\n\t}\n}\n\nfunction insertForkValue(db: SqliteDatabase, sessionId: string, stored: StoredValue<unknown>): void {\n\tsetScalarValueRow(db, sessionId, stored.address.namespace, stored.address.key, stored.seq, stored.value);\n}\n\nfunction updateForkSessionStats(db: SqliteDatabase, sessionId: string, messageCount: number): void {\n\tsql`UPDATE sessions SET message_count = ${messageCount} WHERE id = ${sessionId}`.run(db);\n}\n\nexport class SqliteSessionRepo {\n\tprivate readonly directory: string;\n\tprivate readonly databasePath: string | undefined;\n\tprivate readonly databaseFactory: SqliteDatabaseFactory;\n\tprivate readonly now: () => number;\n\tprivate readonly pendingIds = new Set<string>();\n\tprivate readonly openStorages = new Map<string, SqliteStorage>();\n\tprivate readonly openSessions = new Set<SqliteOpenSession>();\n\tprivate closed = false;\n\tprivate closePromise: Promise<void> | undefined;\n\n\tconstructor(options: SqliteSessionRepoOptions) {\n\t\tthis.directory = options.directory;\n\t\tthis.databasePath = options.databasePath;\n\t\tthis.databaseFactory = options.databaseFactory;\n\t\tthis.now = options.now ?? Date.now;\n\t}\n\n\tasync create(options: SqliteSessionCreateOptions | undefined, _context: Context): Promise<SqliteOpenSession> {\n\t\tthis.assertOpen();\n\t\toptions ??= {};\n\t\tconst createdAt = this.now();\n\t\tconst id = options.id ?? uuidv7(createdAt);\n\t\tthis.reserveId(id);\n\t\tconst path = this.pathForSession(id);\n\t\tlet db: SqliteDatabase | undefined;\n\t\tlet reservedFile = false;\n\t\tlet initialized = false;\n\t\tlet session: SqliteOpenSession | undefined;\n\t\ttry {\n\t\t\tawait mkdir(dirname(path), { recursive: true });\n\t\t\tif (!this.usesSharedDatabase()) {\n\t\t\t\tconst file = await openFile(path, \"wx\");\n\t\t\t\tawait file.close();\n\t\t\t\treservedFile = true;\n\t\t\t}\n\t\t\tconst activeDb = await this.databaseFactory.open(path);\n\t\t\tdb = activeDb;\n\t\t\tconfigureWritableConnection(activeDb);\n\t\t\tawait applyInitialSchema(activeDb);\n\t\t\tconst canonicalPath = await realpath(path);\n\t\t\tconst metadata: SqliteSessionMetadata = {\n\t\t\t\tid,\n\t\t\t\tcreatedAt,\n\t\t\t\tstorageVersion: SQLITE_STORAGE_VERSION,\n\t\t\t\t...(options.parentSessionId === undefined ? {} : { parentSessionId: options.parentSessionId }),\n\t\t\t\tpath: canonicalPath,\n\t\t\t};\n\t\t\tactiveDb.transaction(() => {\n\t\t\t\tif (hasSessionRow(activeDb, id)) throw new Error(`SQLite session already exists: ${id}`);\n\t\t\t\tinsertSessionRow(activeDb, metadata, SQLITE_STORAGE_VERSION, FIRST_AVAILABLE_COMMIT_SEQ);\n\t\t\t});\n\t\t\tinitialized = true;\n\t\t\tsession = this.openStorageBackedSession(metadata, activeDb);\n\t\t\treturn session;\n\t\t} catch (error) {\n\t\t\tif (reservedFile && !initialized) await removeSessionFiles(path, { force: true });\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tif (session === undefined) {\n\t\t\t\ttry {\n\t\t\t\t\tdb?.close();\n\t\t\t\t} finally {\n\t\t\t\t\tthis.pendingIds.delete(id);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tasync open(metadata: SqliteSessionMetadata, _context: Context): Promise<SqliteOpenSession> {\n\t\tthis.assertOpen();\n\t\tthis.reserveId(metadata.id);\n\t\tlet db: SqliteDatabase | undefined;\n\t\tlet session: SqliteOpenSession | undefined;\n\t\ttry {\n\t\t\tconst path = await this.repositoryPathForMetadata(metadata);\n\t\t\tconst activeDb = await this.databaseFactory.openExisting(path);\n\t\t\tdb = activeDb;\n\t\t\tconfigureWritableConnection(activeDb);\n\t\t\tconst stored = metadataFromSessionRow(path, readSessionRow(activeDb, metadata.id), SQLITE_STORAGE_VERSION);\n\t\t\tsession = this.openStorageBackedSession(stored, activeDb);\n\t\t\treturn session;\n\t\t} finally {\n\t\t\tif (session === undefined) {\n\t\t\t\ttry {\n\t\t\t\t\tdb?.close();\n\t\t\t\t} finally {\n\t\t\t\t\tthis.pendingIds.delete(metadata.id);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tasync list(_options: undefined, _context: Context): Promise<SqliteSessionMetadata[]> {\n\t\tthis.assertOpen();\n\t\tlet paths: string[];\n\t\tif (this.usesSharedDatabase()) {\n\t\t\tpaths = [this.databasePath!];\n\t\t} else {\n\t\t\tlet names: string[];\n\t\t\ttry {\n\t\t\t\tnames = await readdir(this.directory);\n\t\t\t} catch (error) {\n\t\t\t\tif (isErrorWithCode(error, \"ENOENT\")) return [];\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tpaths = names\n\t\t\t\t.filter((name) => name.endsWith(SQLITE_SESSION_EXTENSION))\n\t\t\t\t.map((name) => join(this.directory, name));\n\t\t}\n\t\tconst sessions: SqliteSessionMetadata[] = [];\n\t\tfor (const path of paths) {\n\t\t\tlet db: SqliteDatabase | undefined;\n\t\t\ttry {\n\t\t\t\tconst canonicalPath = await realpath(path);\n\t\t\t\tdb = await this.databaseFactory.openReadOnly(canonicalPath);\n\t\t\t\tconfigureReadOnlyConnection(db);\n\t\t\t\tfor (const row of readAllSessionRows(db)) {\n\t\t\t\t\tsessions.push(metadataFromSessionRow(canonicalPath, row, SQLITE_STORAGE_VERSION));\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Discovery is best-effort: corrupt files, incompatible versions, and\n\t\t\t\t// unrelated *.sqlite files are reported when explicitly opened.\n\t\t\t} finally {\n\t\t\t\tdb?.close();\n\t\t\t}\n\t\t}\n\t\treturn sessions.sort((left, right) => right.createdAt - left.createdAt);\n\t}\n\n\tasync delete(metadata: SqliteSessionMetadata, _context: Context): Promise<void> {\n\t\tthis.assertOpen();\n\t\tthis.reserveId(metadata.id);\n\t\ttry {\n\t\t\tconst path = await this.repositoryPathForMetadata(metadata);\n\t\t\tconst db = await this.databaseFactory.openExisting(path);\n\t\t\ttry {\n\t\t\t\tconfigureWritableConnection(db);\n\t\t\t\tif (this.usesSharedDatabase()) {\n\t\t\t\t\tdb.transaction(() => {\n\t\t\t\t\t\tmetadataFromSessionRow(path, readSessionRow(db, metadata.id), SQLITE_STORAGE_VERSION);\n\t\t\t\t\t\tdeleteSessionRows(db, metadata.id);\n\t\t\t\t\t});\n\t\t\t\t} else {\n\t\t\t\t\tmetadataFromSessionRow(path, readSessionRow(db, metadata.id), SQLITE_STORAGE_VERSION);\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tdb.close();\n\t\t\t}\n\t\t\tif (!this.usesSharedDatabase()) await removeSessionFiles(path, { force: false });\n\t\t} finally {\n\t\t\tthis.pendingIds.delete(metadata.id);\n\t\t}\n\t}\n\n\tasync fork(source: SqliteSessionMetadata, options: ForkOptions, context: Context): Promise<SqliteOpenSession> {\n\t\tthis.assertOpen();\n\t\tconst createdAt = this.now();\n\t\tconst id = options.id ?? uuidv7(createdAt);\n\t\tthis.reserveId(id);\n\t\tconst sourceStorage = this.openStorages.get(storageIdentity(source.path, source.id));\n\t\tconst activeSourceSnapshot = sourceStorage?.snapshot(options, context);\n\t\tvoid activeSourceSnapshot?.catch(() => undefined);\n\t\tconst path = this.pathForSession(id);\n\t\tlet db: SqliteDatabase | undefined;\n\t\tlet reservedFile = false;\n\t\tlet initialized = false;\n\t\tlet session: SqliteOpenSession | undefined;\n\t\ttry {\n\t\t\tawait mkdir(dirname(path), { recursive: true });\n\t\t\tif (!this.usesSharedDatabase()) {\n\t\t\t\tconst file = await openFile(path, \"wx\");\n\t\t\t\tawait file.close();\n\t\t\t\treservedFile = true;\n\t\t\t}\n\n\t\t\tconst snapshot =\n\t\t\t\tactiveSourceSnapshot === undefined\n\t\t\t\t\t? await this.createForkSnapshotFromExternalSource(source, options)\n\t\t\t\t\t: buildForkSnapshot(await activeSourceSnapshot, options);\n\n\t\t\tconst activeDb = await this.databaseFactory.open(path);\n\t\t\tdb = activeDb;\n\t\t\tconfigureWritableConnection(activeDb);\n\t\t\tawait applyInitialSchema(activeDb);\n\t\t\tconst canonicalPath = await realpath(path);\n\t\t\tconst metadata: SqliteSessionMetadata = {\n\t\t\t\tid,\n\t\t\t\tcreatedAt,\n\t\t\t\tstorageVersion: SQLITE_STORAGE_VERSION,\n\t\t\t\tparentSessionId: source.id,\n\t\t\t\tpath: canonicalPath,\n\t\t\t};\n\t\t\tactiveDb.transaction(() => {\n\t\t\t\tif (hasSessionRow(activeDb, id)) throw new Error(`SQLite session already exists: ${id}`);\n\t\t\t\tinsertSessionRow(activeDb, metadata, SQLITE_STORAGE_VERSION, snapshot.nextSeq);\n\t\t\t\tconst entryWriter = new EntryRowWriter(activeDb, id);\n\t\t\t\tfor (const entry of snapshot.entries) {\n\t\t\t\t\tentryWriter.insert(entry);\n\t\t\t\t\tappendEntryToBranchIndex(activeDb, id, entry);\n\t\t\t\t}\n\t\t\t\tfor (const stored of snapshot.scalarValues) insertForkValue(activeDb, id, stored);\n\t\t\t\tupdateForkSessionStats(activeDb, id, snapshot.messageCount);\n\t\t\t});\n\t\t\tinitialized = true;\n\t\t\tsession = this.openStorageBackedSession(metadata, activeDb);\n\t\t\treturn session;\n\t\t} catch (error) {\n\t\t\tif (reservedFile && !initialized) await removeSessionFiles(path, { force: true });\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tif (session === undefined) {\n\t\t\t\ttry {\n\t\t\t\t\tdb?.close();\n\t\t\t\t} finally {\n\t\t\t\t\tthis.pendingIds.delete(id);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tclose(context: Context): Promise<void> {\n\t\tif (this.closePromise !== undefined) return this.closePromise;\n\t\tthis.closed = true;\n\t\tthis.closePromise = this.closeOpenSessions(context);\n\t\treturn this.closePromise;\n\t}\n\n\tprivate async createForkSnapshotFromExternalSource(\n\t\tsource: SqliteSessionMetadata,\n\t\toptions: ForkOptions,\n\t): Promise<ForkSnapshot> {\n\t\tconst path = await realpath(source.path);\n\t\tconst sourceDb = await this.databaseFactory.openReadOnly(path);\n\t\ttry {\n\t\t\tconfigureReadOnlyConnection(sourceDb);\n\t\t\treturn createSqliteForkSnapshot(sourceDb, { ...source, path }, options);\n\t\t} finally {\n\t\t\tsourceDb.close();\n\t\t}\n\t}\n\n\tprivate async closeOpenSessions(context: Context): Promise<void> {\n\t\tconst results = await Promise.allSettled([...this.openSessions].map((session) => session.close(context)));\n\t\tconst errors = results.flatMap((result) => (result.status === \"rejected\" ? [result.reason] : []));\n\t\tif (errors.length === 1) throw errors[0];\n\t\tif (errors.length > 1) throw new AggregateError(errors, \"Failed to close SQLite Sessions\");\n\t}\n\n\tprivate openStorageBackedSession(metadata: SqliteSessionMetadata, db: SqliteDatabase): SqliteOpenSession {\n\t\tconst key = storageIdentity(metadata.path, metadata.id);\n\t\tconst storage = new SqliteStorage(db, { sessionId: metadata.id, now: this.now });\n\t\tthis.openStorages.set(key, storage);\n\t\tconst session = new StorageBackedSession(metadata, storage);\n\t\tconst openSession = new SqliteOpenSession(session, {\n\t\t\tonClose: () => {\n\t\t\t\ttry {\n\t\t\t\t\tdb.close();\n\t\t\t\t} finally {\n\t\t\t\t\tif (this.openStorages.get(key) === storage) this.openStorages.delete(key);\n\t\t\t\t\tthis.openSessions.delete(openSession);\n\t\t\t\t\tthis.pendingIds.delete(metadata.id);\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\t\tthis.openSessions.add(openSession);\n\t\treturn openSession;\n\t}\n\n\tprivate async repositoryPathForMetadata(metadata: SqliteSessionMetadata): Promise<string> {\n\t\tconst [expected, actual] = await Promise.all([\n\t\t\trealpath(this.pathForSession(metadata.id)),\n\t\t\trealpath(metadata.path),\n\t\t]);\n\t\tif (expected !== actual) {\n\t\t\tthrow new Error(`SQLite session metadata path is outside this repository: ${metadata.path}`);\n\t\t}\n\t\treturn actual;\n\t}\n\n\tprivate reserveId(id: string): void {\n\t\tif (this.pendingIds.has(id)) throw new Error(`Session is already open: ${id}`);\n\t\tthis.pendingIds.add(id);\n\t}\n\n\tprivate pathForSession(id: string): string {\n\t\treturn this.databasePath ?? sessionPath(this.directory, id);\n\t}\n\n\tprivate usesSharedDatabase(): boolean {\n\t\treturn this.databasePath !== undefined;\n\t}\n\n\tprivate assertOpen(): void {\n\t\tif (this.closed) throw new Error(\"SqliteSessionRepo is closed\");\n\t}\n}\n"]}