immune-brain 3.6.8 → 4.0.0

package/plugins/immune-brain/runtime/kernel/sqlite_store.ts

@@ -0,0 +1,1193 @@
+/**
+ * Kernel authority store: one worktree-local SQLite database is the single
+ * transaction boundary for runs, lifecycle, revisions, findings, attestations
+ * and operation outcomes.
+ *
+ * Layout: `.imm/state/kernel.sqlite` with WAL, `synchronous=FULL`, foreign
+ * keys and a bounded busy timeout. `.imm/state/` stays Git-ignored; the
+ * database is never committed, and audit evidence is exported separately as
+ * tracked, deterministic files.
+ *
+ * This module is mechanical: it opens/validates the database, runs bounded
+ * transactions with revision-checked CAS helpers, and exposes row access.
+ * Authority decisions (owner matrix, settlement rules, replay identity) stay
+ * in `storage.ts` and the reducer.
+ */
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import {
+	constants,
+	closeSync,
+	copyFileSync,
+	existsSync,
+	fsyncSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	realpathSync,
+	statSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+import {
+	KERNEL_DB_RELATIVE,
+	KERNEL_STORE_SCHEMA_VERSION,
+	kernelStoreBindingDigest,
+	kernelStoreIdentityPath,
+} from "./storage_paths";
+
+export { KERNEL_STORE_SCHEMA_VERSION };
+
+export const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+
+/** Schema/version rejection and unsafe-store diagnostics. */
+export class KernelStoreSecurityError extends Error {
+	readonly code: string = "kernel_store_security_error";
+
+	constructor(message: string) {
+		super(message);
+		this.name = "KernelStoreSecurityError";
+	}
+}
+
+/** Revision conflicts, busy stores and unrecoverable transaction failures. */
+export class KernelStoreConflictError extends Error {
+	readonly code: string = "kernel_store_conflict";
+
+	constructor(message: string) {
+		super(message);
+		this.name = "KernelStoreConflictError";
+	}
+}
+
+/** The database exists but its schema version is not the one this runtime owns. */
+export class KernelSchemaError extends KernelStoreSecurityError {
+	readonly code = "kernel_schema_error";
+
+	constructor(message: string) {
+		super(message);
+		this.name = "KernelSchemaError";
+	}
+}
+
+export type RunLifecycleState = "active" | "done" | "stopped";
+export type RunClaimStatus = "active" | "draining";
+
+export interface KernelWorkspaceRow {
+	revision: number;
+	current_run_id: string | null;
+	updated_at: string;
+}
+
+export interface KernelRunRow {
+	run_id: string;
+	task_id: string;
+	state: RunLifecycleState;
+	revision: number;
+	record_json: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	enrollment_event_id: string;
+	claim_status: RunClaimStatus | null;
+	created_at: string;
+	updated_at: string;
+	terminal_proof_json: string | null;
+	terminal_at: string | null;
+	audit_exported_at: string | null;
+	pending_relocations_json: string | null;
+}
+
+export interface KernelOperationRow {
+	operation_id: string;
+	kind: string;
+	run_id: string | null;
+	result_json: string;
+	committed_at: string;
+}
+
+export interface KernelJournalRow {
+	seq: number;
+	entry_json: string;
+	task_id: string | null;
+	observation_commit_id: string | null;
+	observation_id: string | null;
+}
+
+export interface KernelRunInsert {
+	run_id: string;
+	task_id: string;
+	record_json: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	enrollment_event_id: string;
+	claim_status: RunClaimStatus;
+	created_at: string;
+	updated_at: string;
+}
+
+interface OpenStore {
+	db: DatabaseSync;
+	depth: number;
+}
+
+const openStores = new Map<string, OpenStore>();
+
+let storeFaultForTest: (() => void) | null = null;
+
+/**
+ * Test-only seam: runs after every authority write of the current transaction
+ * and immediately before COMMIT, so a thrown fault must roll the transaction
+ * back completely.
+ */
+export function setStoreFaultForTest(hook: (() => void) | null): void {
+	storeFaultForTest = hook;
+}
+
+function runStoreFault(): void {
+	const hook = storeFaultForTest;
+	storeFaultForTest = null;
+	hook?.();
+}
+
+function canonicalRoot(root: string): string {
+	try {
+		return realpathSync(root);
+	} catch {
+		throw new KernelStoreSecurityError("project root is unavailable");
+	}
+}
+
+function storeKey(root: string): string {
+	return canonicalRoot(root);
+}
+
+export function kernelStorePath(root: string): string {
+	return resolve(canonicalRoot(root), KERNEL_DB_RELATIVE);
+}
+
+function assertSafeSegments(canonical: string, candidate: string): void {
+	let current = canonical;
+	for (const segment of relative(canonical, candidate).split(sep).filter(Boolean)) {
+		current = resolve(current, segment);
+		let stat;
+		try {
+			stat = lstatSync(current);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || code === "ENOTDIR") continue;
+			throw error;
+		}
+		if (stat.isSymbolicLink())
+			throw new KernelStoreSecurityError(
+				`symlink storage segment is forbidden: ${relative(canonical, current)}`,
+			);
+	}
+}
+
+/** Reject a store path that is not a regular file inside the worktree. */
+function assertSafeStoreTarget(canonical: string, target: string): void {
+	assertSafeSegments(canonical, target);
+	try {
+		const stat = lstatSync(target);
+		if (stat.isSymbolicLink())
+			throw new KernelStoreSecurityError(
+				`symlink storage segment is forbidden: ${relative(canonical, target)}`,
+			);
+		if (!stat.isFile())
+			throw new KernelStoreSecurityError("kernel store is not a regular file");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+function ensureStoreDirectory(canonical: string): void {
+	const target = resolve(canonical, KERNEL_DB_RELATIVE);
+	const directory = dirname(target);
+	assertSafeSegments(canonical, directory);
+	let current = canonical;
+	for (const segment of relative(canonical, directory).split(sep).filter(Boolean)) {
+		current = resolve(current, segment);
+		let stat;
+		try {
+			stat = lstatSync(current);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+			stat = null;
+		}
+		if (!stat) {
+			mkdirSync(current);
+			continue;
+		}
+		if (stat.isSymbolicLink())
+			throw new KernelStoreSecurityError(
+				`symlink storage segment is forbidden: ${relative(canonical, current)}`,
+			);
+		if (!stat.isDirectory())
+			throw new KernelStoreSecurityError(
+				`storage segment is not a directory: ${relative(canonical, current)}`,
+			);
+	}
+	assertSafeStoreTarget(canonical, target);
+}
+
+export function kernelStoreExists(root: string): boolean {
+	return existsSync(kernelStorePath(root));
+}
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS store_meta (
+	key TEXT PRIMARY KEY,
+	value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS workspace (
+	id INTEGER PRIMARY KEY CHECK (id = 1),
+	revision INTEGER NOT NULL,
+	current_run_id TEXT,
+	updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS runs (
+	run_id TEXT PRIMARY KEY,
+	task_id TEXT NOT NULL UNIQUE,
+	state TEXT NOT NULL CHECK (state IN ('active','done','stopped')),
+	revision INTEGER NOT NULL,
+	record_json TEXT NOT NULL,
+	intent_revision INTEGER NOT NULL,
+	intent_content_hash TEXT NOT NULL,
+	enrollment_event_id TEXT NOT NULL,
+	claim_status TEXT CHECK (claim_status IN ('active','draining')),
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL,
+	terminal_proof_json TEXT,
+	terminal_at TEXT,
+	audit_exported_at TEXT,
+	pending_relocations_json TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS runs_single_active ON runs((1)) WHERE state = 'active';
+CREATE INDEX IF NOT EXISTS runs_state ON runs(state);
+CREATE TABLE IF NOT EXISTS operations (
+	operation_id TEXT PRIMARY KEY,
+	kind TEXT NOT NULL,
+	run_id TEXT,
+	result_json TEXT NOT NULL,
+	committed_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS journal (
+	seq INTEGER PRIMARY KEY AUTOINCREMENT,
+	entry_json TEXT NOT NULL,
+	task_id TEXT,
+	observation_commit_id TEXT,
+	observation_id TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS journal_observation_commit ON journal(observation_commit_id) WHERE observation_commit_id IS NOT NULL;
+`;
+
+function workspaceBinding(root: string, workspaceId: string): string {
+	return kernelStoreBindingDigest(root, workspaceId);
+}
+
+function gitCommonDir(root: string): string | null {
+	const result = spawnSync("git", ["-C", root, "rev-parse", "--git-common-dir"], {
+		encoding: "utf8",
+	});
+	if (result.status !== 0) return null;
+	const value = result.stdout.trim();
+	if (!value) return null;
+	return isAbsolute(value) ? value : resolve(root, value);
+}
+
+function readMeta(db: DatabaseSync, key: string): string | null {
+	const row = db.prepare("SELECT value FROM store_meta WHERE key = ?").get(key) as
+		| { value?: unknown }
+		| undefined;
+	return row && typeof row.value === "string" ? row.value : null;
+}
+
+function writeMeta(db: DatabaseSync, key: string, value: string): void {
+	db.prepare(
+		"INSERT INTO store_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+	).run(key, value);
+}
+
+function applyPragmas(db: DatabaseSync, busyTimeoutMs: number, writable: boolean): void {
+	// Read-only accessors must not switch journal mode or checkpoint: a read
+	// never changes the store bytes it observes.
+	if (writable) {
+		db.exec("PRAGMA journal_mode = WAL");
+		db.exec("PRAGMA synchronous = FULL");
+	}
+	db.exec("PRAGMA foreign_keys = ON");
+	db.exec(`PRAGMA busy_timeout = ${Math.max(1, Math.trunc(busyTimeoutMs))}`);
+}
+
+function assertSchema(db: DatabaseSync, root: string): void {
+	const rows = db
+		.prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+		.all() as Array<{ name?: unknown }>;
+	const tables = new Set(rows.map((row) => String(row.name)));
+	if (tables.size === 0) {
+		// A tableless file is either a brand-new store (created by the lock or by
+		// this open) or a store that lost its contents. The creation marker tells
+		// them apart: an existing identity means this worktree had a store, so
+		// re-initializing would silently replace real authority with an empty
+		// workspace. Fail closed and name the recovery.
+		if (existsSync(resolve(root, kernelStoreIdentityPath())))
+			throw new KernelStoreSecurityError(
+				"kernel store exists but carries no schema; restore .imm/state/kernel.sqlite from backup or remove the state directory deliberately to start a new worktree identity",
+			);
+		return;
+	}
+	if (!tables.has("store_meta") || !tables.has("runs") || !tables.has("workspace")) {
+		throw new KernelSchemaError(
+			"kernel store schema is not recognizable; the database was not created by this runtime",
+		);
+	}
+	const version = readMeta(db, "schema_version");
+	if (version !== String(KERNEL_STORE_SCHEMA_VERSION)) {
+		throw new KernelSchemaError(
+			`kernel store schema version ${version ?? "missing"} is incompatible with this runtime (${KERNEL_STORE_SCHEMA_VERSION}); run the supported migration before mutating`,
+		);
+	}
+	const workspaceId = readMeta(db, "workspace_id");
+	const binding = readMeta(db, "workspace_binding");
+	if (!workspaceId || !binding)
+		throw new KernelSchemaError("kernel store identity metadata is missing");
+	if (workspaceBinding(root, workspaceId) !== binding)
+		throw new KernelStoreSecurityError(
+			"kernel store belongs to a different worktree; restore it into its binding worktree or run the supported rebinding",
+		);
+}
+
+/**
+ * Record that this worktree has a store. Written once, at first initialization:
+ * it is the only surviving evidence that a later tableless database is a
+ * damaged store rather than a new one.
+ */
+function writeStoreIdentity(root: string): void {
+	const path = resolve(root, kernelStoreIdentityPath());
+	if (existsSync(path)) return;
+	// Durable creation: the marker is the only evidence that a later tableless
+	// database is a damaged store rather than a new one.
+	const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+	try {
+		writeFileSync(fd, `${JSON.stringify({ contract: "assurance_kernel/store_identity/v1", created_at: new Date().toISOString() }, null, 2)}\n`);
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	const directory = openSync(dirname(path), constants.O_RDONLY);
+	try {
+		fsyncSync(directory);
+	} finally {
+		closeSync(directory);
+	}
+}
+
+/** Ensure the store identity marker exists; idempotent and durable. */
+export function ensureStoreIdentity(root: string): void {
+	assertSafeStoreTarget(canonicalRoot(root), resolve(root, kernelStoreIdentityPath()));
+	writeStoreIdentity(canonicalRoot(root));
+}
+
+function initializeSchema(db: DatabaseSync, root: string, now: string): void {
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		db.exec(SCHEMA_SQL);
+		const workspaceId = readMeta(db, "workspace_id") ?? randomUUID();
+		writeMeta(db, "workspace_id", workspaceId);
+		writeMeta(db, "schema_version", String(KERNEL_STORE_SCHEMA_VERSION));
+		writeMeta(db, "workspace_binding", workspaceBinding(root, workspaceId));
+		writeMeta(db, "created_at", readMeta(db, "created_at") ?? now);
+		const common = gitCommonDir(root);
+		if (common) writeMeta(db, "git_common_dir", common);
+		db.prepare(
+			"INSERT INTO workspace (id, revision, current_run_id, updated_at) VALUES (1, 0, NULL, ?) ON CONFLICT(id) DO NOTHING",
+		).run(now);
+		db.exec("COMMIT");
+	} catch (error) {
+		try {
+			db.exec("ROLLBACK");
+		} catch {
+			// The transaction is already closed.
+		}
+		throw error;
+	}
+}
+
+function fsyncPath(path: string): void {
+	const fd = openSync(path, constants.O_RDONLY);
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function fsyncDirectory(path: string): void {
+	const fd = openSync(path, constants.O_RDONLY);
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/**
+ * Create one fully initialized store file at an explicit in-worktree path.
+ *
+ * The explicit legacy importer builds its candidate store here — under
+ * `.imm/state/`, never at the canonical path — verifies it, and only then
+ * publishes it. Initialization runs the same schema, meta and workspace binding
+ * as a first normal open, so a published migration store passes `assertSchema`.
+ */
+export function createMigrationStoreFile(root: string, targetPath: string, now: string): void {
+	const canonical = canonicalRoot(root);
+	const resolved = resolve(targetPath);
+	assertSafeStoreTarget(canonical, resolved);
+	assertSafeSegments(canonical, resolved);
+	ensureStoreDirectory(canonical);
+	if (existsSync(resolved)) throw new KernelStoreSecurityError(`migration store already exists at ${targetPath}`);
+	const db = new DatabaseSync(resolved);
+	try {
+		applyPragmas(db, DEFAULT_BUSY_TIMEOUT_MS, true);
+		initializeSchema(db, canonical, now);
+		db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+		// Leave the candidate in rollback-journal mode: a WAL sidecar would not
+		// travel with the publication rename, and the first runtime open converts
+		// the store back to WAL.
+		db.exec("PRAGMA journal_mode=DELETE");
+	} finally {
+		db.close();
+	}
+	fsyncPath(resolved);
+}
+
+/**
+ * Verify one store file against this worktree's schema and binding.
+ *
+ * The importer runs this on its candidate before publication, so a database
+ * built for another worktree, or by an incompatible runtime, can never replace
+ * the authority of this one.
+ */
+export function verifyStoreFile(root: string, path: string): void {
+	const canonical = canonicalRoot(root);
+	const resolved = resolve(path);
+	assertSafeStoreTarget(canonical, resolved);
+	const db = openStoreFile(canonical, resolved, { readOnly: true });
+	if (!db) throw new KernelStoreSecurityError(`store file is missing: ${path}`);
+	db.close();
+}
+
+/**
+ * Classify a store file's identity without asserting anything about its rows.
+ *
+ * The importer needs to tell three states apart: a file whose schema never
+ * committed (safe to rebuild), a file that belongs to another worktree (never
+ * ours), and a file that is bound to this worktree (its content is the only
+ * question left).
+ */
+export function classifyStoreFile(root: string, path: string): "uninitialized" | "foreign" | "binding_ok" {
+	const canonical = canonicalRoot(root);
+	const resolved = resolve(path);
+	assertSafeStoreTarget(canonical, resolved);
+	let db: DatabaseSync;
+	try {
+		db = new DatabaseSync(resolved, { readOnly: true });
+	} catch {
+		return "uninitialized";
+	}
+	try {
+		const rows = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all() as Array<{ name?: unknown }>;
+		if (!new Set(rows.map((row) => String(row.name))).has("store_meta")) return "uninitialized";
+		const workspaceId = readMeta(db, "workspace_id");
+		const binding = readMeta(db, "workspace_binding");
+		if (!workspaceId || !binding) return "uninitialized";
+		return workspaceBinding(canonical, workspaceId) === binding ? "binding_ok" : "foreign";
+	} catch {
+		return "uninitialized";
+	} finally {
+		db.close();
+	}
+}
+
+/**
+ * Publish a verified migration store at the canonical path.
+ *
+ * The rename is the publication point: a crash before it leaves the canonical
+ * store absent, and a crash after it leaves a complete store, so no reader can
+ * ever observe a half-imported database. Nothing is written to the canonical
+ * path when it already exists.
+ */
+export function publishMigrationStoreFile(root: string, sourcePath: string): void {
+	const canonical = canonicalRoot(root);
+	const target = resolve(canonical, KERNEL_DB_RELATIVE);
+	const source = resolve(sourcePath);
+	assertSafeStoreTarget(canonical, source);
+	assertSafeSegments(canonical, source);
+	if (existsSync(target)) throw new KernelStoreConflictError("kernel store already exists; refusing to overwrite authority");
+	// The candidate must be self-contained: a WAL beside the renamed database
+	// would make the published store unreadable, so only empty sidecars may
+	// remain and they are removed before publication.
+	for (const sidecar of [`${source}-wal`, `${source}-shm`]) {
+		if (!existsSync(sidecar)) continue;
+		if (statSync(sidecar).size > 0)
+			throw new KernelStoreConflictError("migration store still carries a write-ahead log; checkpoint it before publishing");
+		rmSync(sidecar, { force: true });
+	}
+	fsyncPath(source);
+	renameSync(source, target);
+	fsyncDirectory(dirname(target));
+	writeStoreIdentity(canonical);
+}
+
+/**
+ * Open the worktree authority store. `create: false` returns null when the
+ * database does not exist yet, so read-only paths never create one.
+ */
+export function openKernelStore(
+	root: string,
+	options: { create?: boolean; busyTimeoutMs?: number; now?: string; readOnly?: boolean } = {},
+): DatabaseSync | null {
+	const canonical = canonicalRoot(root);
+	const path = resolve(canonical, KERNEL_DB_RELATIVE);
+	const create = options.create ?? true;
+	if (!existsSync(path) && !create) return null;
+	// Safety validation applies to reads as well: following a symlinked store
+	// would read (or create) authority outside the worktree.
+	assertSafeStoreTarget(canonical, path);
+	if (!options.readOnly) ensureStoreDirectory(canonical);
+	return openStoreFile(canonical, path, options);
+}
+
+/**
+ * Open and validate one store file against a worktree binding. `assertSchema`
+ * runs before the caller can read or write anything, which is what lets a
+ * restore validate a backup copy in place without touching the live store.
+ */
+function openStoreFile(
+	canonical: string,
+	path: string,
+	options: { busyTimeoutMs?: number; now?: string; readOnly?: boolean } = {},
+): DatabaseSync | null {
+	let db: DatabaseSync;
+	try {
+		db = new DatabaseSync(path, options.readOnly ? { readOnly: true } : {});
+	} catch (error) {
+		throw new KernelStoreSecurityError(
+			`kernel store could not be opened at ${KERNEL_DB_RELATIVE}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	try {
+		applyPragmas(db, options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS, !options.readOnly);
+		assertSchema(db, canonical);
+		const initialized =
+			(db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='store_meta'").get() as
+				| { name?: unknown }
+				| undefined) !== undefined;
+		if (!initialized) {
+			if (options.readOnly) {
+				// A read against a store that has no schema yet: there is nothing to
+				// read and nothing to create, so report "no store" instead of
+				// inventing one through a write from a read path.
+				db.close();
+				return null;
+			}
+			initializeSchema(db, canonical, options.now ?? new Date().toISOString());
+			writeStoreIdentity(canonical);
+		}
+		return db;
+	} catch (error) {
+		try {
+			db.close();
+		} catch {
+			// nothing to close
+		}
+		throw error;
+	}
+}
+
+function closeQuietly(db: DatabaseSync): void {
+	try {
+		db.close();
+	} catch {
+		// Already closed.
+	}
+}
+
+/**
+ * Run `operation` inside one bounded, revision-checked write transaction.
+ * Nested calls in the same process reuse the open connection, so authority
+ * helpers that assume an already-held lock stay composable. Cross-process
+ * writers are serialized by SQLite's write lock and the bounded busy timeout.
+ */
+export function withKernelTransaction<T>(
+	root: string,
+	operation: (db: DatabaseSync) => T,
+	options: { busyTimeoutMs?: number; now?: string } = {},
+): T {
+	const key = storeKey(root);
+	const existing = openStores.get(key);
+	if (existing) {
+		existing.depth += 1;
+		try {
+			return operation(existing.db);
+		} finally {
+			existing.depth -= 1;
+		}
+	}
+	let db: DatabaseSync | null = null;
+	try {
+		db = openKernelStore(root, options);
+	} catch (error) {
+		if (error instanceof Error && error.message.includes("database is locked"))
+			throw new KernelStoreConflictError(
+				"kernel store is busy: another writer holds the store lock",
+			);
+		throw error;
+	}
+	if (!db) throw new KernelStoreSecurityError("kernel store could not be opened");
+	const handle: OpenStore = { db, depth: 1 };
+	openStores.set(key, handle);
+	try {
+		try {
+			db.exec("BEGIN IMMEDIATE");
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (message.includes("locked") || message.includes("busy"))
+				throw new KernelStoreConflictError(
+					"kernel store is busy: another writer holds the store lock",
+				);
+			throw new KernelStoreConflictError(`kernel store transaction could not start: ${message}`);
+		}
+		let result: T;
+		try {
+			result = operation(db);
+			// The fault seam runs after the authority writes and before COMMIT,
+			// so a thrown fault must roll the whole transaction back.
+			runStoreFault();
+			db.exec("COMMIT");
+		} catch (error) {
+			try {
+				db.exec("ROLLBACK");
+			} catch {
+				// A failed rollback leaves recovery to SQLite's own journal.
+			}
+			if (error instanceof Error && error.message.startsWith("kernel store transaction failed to commit"))
+				throw error;
+			const message = error instanceof Error ? error.message : String(error);
+			if (message.includes("SQLITE_BUSY") || message.includes("database is locked"))
+				throw new KernelStoreConflictError(
+					`kernel store transaction failed to commit: ${message}`,
+				);
+			throw error;
+		}
+		return result;
+	} finally {
+		openStores.delete(key);
+		closeQuietly(db);
+	}
+}
+
+/** Run a read-only operation against the store when it exists. */
+export function withKernelRead<T>(
+	root: string,
+	operation: (db: DatabaseSync) => T,
+	options: { busyTimeoutMs?: number } = {},
+): T | null {
+	const existing = openStores.get(storeKey(root));
+	if (existing) return operation(existing.db);
+	let db: DatabaseSync | null;
+	try {
+		db = openKernelStore(root, { ...options, create: false, readOnly: true });
+	} catch (error) {
+		// A cleanly closed WAL database keeps no `-shm` file, and a read-only
+		// connection is not allowed to rebuild it. Fall back to a plain
+		// connection: reading still never changes authority, and SQLite only
+		// materializes its own journal state.
+		const message = error instanceof Error ? error.message : String(error);
+		if (!/unable to open database file|CANTOPEN|readonly/i.test(message)) throw error;
+		db = openKernelStore(root, { ...options, create: false });
+	}
+	if (!db) return null;
+	try {
+		return operation(db);
+	} finally {
+		closeQuietly(db);
+	}
+}
+
+export function activeRunId(db: DatabaseSync): string | null {
+	const row = db.prepare("SELECT current_run_id FROM workspace WHERE id = 1").get() as
+		| { current_run_id?: unknown }
+		| undefined;
+	const value = row?.current_run_id;
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function readWorkspaceRow(db: DatabaseSync): KernelWorkspaceRow {
+	const row = db
+		.prepare("SELECT revision, current_run_id, updated_at FROM workspace WHERE id = 1")
+		.get() as { revision?: unknown; current_run_id?: unknown; updated_at?: unknown } | undefined;
+	if (!row) throw new KernelStoreSecurityError("kernel store workspace row is missing");
+	return {
+		revision: Number(row.revision),
+		current_run_id:
+			typeof row.current_run_id === "string" && row.current_run_id.length > 0
+				? row.current_run_id
+				: null,
+		updated_at: String(row.updated_at ?? ""),
+	};
+}
+
+/** CAS workspace: `expectedRevision` must equal the stored revision. */
+export function writeWorkspaceRow(
+	db: DatabaseSync,
+	expectedRevision: number,
+	currentRunId: string | null,
+	updatedAt: string,
+): number {
+	const result = db
+		.prepare(
+			"UPDATE workspace SET revision = revision + 1, current_run_id = ?, updated_at = ? WHERE id = 1 AND revision = ?",
+		)
+		.run(currentRunId, updatedAt, expectedRevision);
+	if (Number(result.changes) !== 1)
+		throw new KernelStoreConflictError(
+			`CAS mismatch for workspace: expected revision ${expectedRevision}`,
+		);
+	return expectedRevision + 1;
+}
+
+function mapRunRow(raw: Record<string, unknown>): KernelRunRow {
+	return {
+		run_id: String(raw.run_id),
+		task_id: String(raw.task_id),
+		state: raw.state as RunLifecycleState,
+		revision: Number(raw.revision),
+		record_json: String(raw.record_json),
+		intent_revision: Number(raw.intent_revision),
+		intent_content_hash: String(raw.intent_content_hash),
+		enrollment_event_id: String(raw.enrollment_event_id),
+		claim_status: (raw.claim_status ?? null) as RunClaimStatus | null,
+		created_at: String(raw.created_at),
+		updated_at: String(raw.updated_at),
+		terminal_proof_json:
+			typeof raw.terminal_proof_json === "string" ? raw.terminal_proof_json : null,
+		terminal_at: typeof raw.terminal_at === "string" ? raw.terminal_at : null,
+		audit_exported_at:
+			typeof raw.audit_exported_at === "string" ? raw.audit_exported_at : null,
+		pending_relocations_json:
+			typeof raw.pending_relocations_json === "string" ? raw.pending_relocations_json : null,
+	};
+}
+
+export function readRunRowByTask(db: DatabaseSync, taskId: string): KernelRunRow | null {
+	const row = db.prepare("SELECT * FROM runs WHERE task_id = ?").get(taskId) as
+		| Record<string, unknown>
+		| undefined;
+	return row ? mapRunRow(row) : null;
+}
+
+export function readRunRowById(db: DatabaseSync, runId: string): KernelRunRow | null {
+	const row = db.prepare("SELECT * FROM runs WHERE run_id = ?").get(runId) as
+		| Record<string, unknown>
+		| undefined;
+	return row ? mapRunRow(row) : null;
+}
+
+export function readActiveRun(db: DatabaseSync): KernelRunRow | null {
+	const row = db.prepare("SELECT * FROM runs WHERE state = 'active'").get() as
+		| Record<string, unknown>
+		| undefined;
+	return row ? mapRunRow(row) : null;
+}
+
+export function listTerminalRuns(db: DatabaseSync): KernelRunRow[] {
+	const rows = db
+		.prepare("SELECT * FROM runs WHERE state <> 'active' ORDER BY updated_at, task_id")
+		.all() as Array<Record<string, unknown>>;
+	return rows.map(mapRunRow);
+}
+
+export function listPendingAuditExports(db: DatabaseSync): KernelRunRow[] {
+	const rows = db
+		.prepare(
+			"SELECT * FROM runs WHERE state <> 'active' AND terminal_proof_json IS NOT NULL AND audit_exported_at IS NULL ORDER BY updated_at, task_id",
+		)
+		.all() as Array<Record<string, unknown>>;
+	return rows.map(mapRunRow);
+}
+
+export function insertRunRow(db: DatabaseSync, run: KernelRunInsert): KernelRunRow {
+	try {
+		db.prepare(
+			`INSERT INTO runs (run_id, task_id, state, revision, record_json, intent_revision, intent_content_hash, enrollment_event_id, claim_status, created_at, updated_at, terminal_proof_json, terminal_at, audit_exported_at, pending_relocations_json)
+			 VALUES (?, ?, 'active', 1, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL)`,
+		).run(
+			run.run_id,
+			run.task_id,
+			run.record_json,
+			run.intent_revision,
+			run.intent_content_hash,
+			run.enrollment_event_id,
+			run.claim_status,
+			run.created_at,
+			run.updated_at,
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.includes("runs_single_active") || message.includes("runs.task_id"))
+			throw new KernelStoreConflictError(
+				`kernel store refused a second active run: ${message}`,
+			);
+		throw error;
+	}
+	const inserted = readRunRowById(db, run.run_id);
+	if (!inserted) throw new KernelStoreSecurityError("kernel store run insert did not converge");
+	return inserted;
+}
+
+/** CAS a record update on one exact run. */
+export function updateRunRecord(
+	db: DatabaseSync,
+	runId: string,
+	expectedRevision: number,
+	recordJson: string,
+	updatedAt: string,
+): number {
+	const result = db
+		.prepare(
+			"UPDATE runs SET revision = revision + 1, record_json = ?, updated_at = ? WHERE run_id = ? AND revision = ?",
+		)
+		.run(recordJson, updatedAt, runId, expectedRevision);
+	if (Number(result.changes) !== 1)
+		throw new KernelStoreConflictError(
+			`CAS mismatch for run ${runId}: expected revision ${expectedRevision}`,
+		);
+	return expectedRevision + 1;
+}
+
+export function updateRunClaim(
+	db: DatabaseSync,
+	runId: string,
+	expectedClaimStatus: RunClaimStatus,
+	nextClaimStatus: RunClaimStatus,
+	updatedAt: string,
+): void {
+	const result = db
+		.prepare(
+			"UPDATE runs SET claim_status = ?, updated_at = ? WHERE run_id = ? AND claim_status = ?",
+		)
+		.run(nextClaimStatus, updatedAt, runId, expectedClaimStatus);
+	if (Number(result.changes) !== 1)
+		throw new KernelStoreConflictError(
+			`CAS mismatch for run ${runId} claim ${expectedClaimStatus}`,
+		);
+}
+
+export function updateRunTerminal(
+	db: DatabaseSync,
+	runId: string,
+	state: Exclude<RunLifecycleState, "active">,
+	recordJson: string,
+	proofJson: string,
+	updatedAt: string,
+): void {
+	const result = db
+		.prepare(
+			`UPDATE runs SET state = ?, record_json = ?, terminal_proof_json = ?, terminal_at = ?, updated_at = ?, claim_status = NULL
+			 WHERE run_id = ? AND state = 'active'`,
+		)
+		.run(state, recordJson, proofJson, updatedAt, updatedAt, runId);
+	if (Number(result.changes) !== 1)
+		throw new KernelStoreConflictError(
+			`terminal settlement refused for run ${runId}: the run is not active`,
+		);
+}
+
+/** Record the document relocations a committed record write still owes. */
+export function setPendingRelocations(
+	db: DatabaseSync,
+	runId: string,
+	relocationsJson: string | null,
+): void {
+	db.prepare("UPDATE runs SET pending_relocations_json = ? WHERE run_id = ?").run(
+		relocationsJson,
+		runId,
+	);
+}
+
+export function listPendingRelocations(db: DatabaseSync): KernelRunRow[] {
+	const rows = db
+		.prepare("SELECT * FROM runs WHERE pending_relocations_json IS NOT NULL ORDER BY updated_at, task_id")
+		.all() as Array<Record<string, unknown>>;
+	return rows.map(mapRunRow);
+}
+
+export function markAuditExported(db: DatabaseSync, runId: string, at: string): void {
+	db.prepare("UPDATE runs SET audit_exported_at = ? WHERE run_id = ?").run(at, runId);
+}
+
+export function readOperationRow(
+	db: DatabaseSync,
+	operationId: string,
+): KernelOperationRow | null {
+	const row = db.prepare("SELECT * FROM operations WHERE operation_id = ?").get(operationId) as
+		| Record<string, unknown>
+		| undefined;
+	if (!row) return null;
+	return {
+		operation_id: String(row.operation_id),
+		kind: String(row.kind),
+		run_id: typeof row.run_id === "string" ? row.run_id : null,
+		result_json: String(row.result_json),
+		committed_at: String(row.committed_at),
+	};
+}
+
+export function insertOperationRow(db: DatabaseSync, row: KernelOperationRow): void {
+	try {
+		db.prepare(
+			"INSERT INTO operations (operation_id, kind, run_id, result_json, committed_at) VALUES (?, ?, ?, ?, ?)",
+		).run(row.operation_id, row.kind, row.run_id, row.result_json, row.committed_at);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new KernelStoreConflictError(`operation ${row.operation_id} was already committed: ${message}`);
+	}
+}
+
+export function appendJournalRow(
+	db: DatabaseSync,
+	entryJson: string,
+	taskId: string | null,
+	observationCommitId: string | null,
+	observationId: string | null,
+): number {
+	const result = db
+		.prepare(
+			"INSERT INTO journal (entry_json, task_id, observation_commit_id, observation_id) VALUES (?, ?, ?, ?)",
+		)
+		.run(entryJson, taskId, observationCommitId, observationId);
+	return Number(result.lastInsertRowid);
+}
+
+export function findJournalObservation(
+	db: DatabaseSync,
+	observationCommitId: string,
+): { observation_id: string | null } | null {
+	const row = db
+		.prepare("SELECT observation_id FROM journal WHERE observation_commit_id = ? LIMIT 1")
+		.get(observationCommitId) as { observation_id?: unknown } | undefined;
+	if (!row) return null;
+	return {
+		observation_id: typeof row.observation_id === "string" ? row.observation_id : null,
+	};
+}
+
+export function readJournalRows(db: DatabaseSync, limit = 1000): KernelJournalRow[] {
+	const rows = db
+		.prepare("SELECT * FROM journal ORDER BY seq LIMIT ?")
+		.all(limit) as Array<Record<string, unknown>>;
+	return rows.map((raw) => ({
+		seq: Number(raw.seq),
+		entry_json: String(raw.entry_json),
+		task_id: typeof raw.task_id === "string" ? raw.task_id : null,
+		observation_commit_id:
+			typeof raw.observation_commit_id === "string" ? raw.observation_commit_id : null,
+		observation_id: typeof raw.observation_id === "string" ? raw.observation_id : null,
+	}));
+}
+
+/** Stable path digests used for snapshot refs and audit identity metadata. */
+export function workspaceIdentity(db: DatabaseSync): string {
+	const value = readMeta(db, "workspace_id");
+	if (!value) throw new KernelSchemaError("kernel store identity metadata is missing");
+	return value;
+}
+
+/**
+ * Consistent, closed-state backup. `VACUUM INTO` writes a checkpointed copy
+ * that never contains a half-applied transaction.
+ */
+export function backupKernelStore(root: string, targetPath: string): void {
+	const canonical = canonicalRoot(root);
+	if (openStores.has(canonical))
+		throw new KernelStoreConflictError("kernel store backup requires the store to be idle");
+	const db = openKernelStore(root, { create: false });
+	if (!db) throw new KernelStoreConflictError("kernel store does not exist");
+	try {
+		const target = resolve(targetPath);
+		const live = resolve(canonical, KERNEL_DB_RELATIVE);
+		for (const forbidden of [live, `${live}-wal`, `${live}-shm`])
+			if (samePath(target, forbidden))
+				throw new KernelStoreSecurityError(
+					"a backup target must not be the live store or its sidecars",
+				);
+		// Write the backup beside its target, durably, and only then replace any
+		// existing backup: a failed or interrupted backup must never cost the
+		// last good copy.
+		mkdirSync(dirname(target), { recursive: true });
+		const temp = `${target}.${randomUUID()}.backup`;
+		rmSync(temp, { force: true });
+		try {
+			db.prepare(`VACUUM INTO '${temp.replace(/'/g, "''")}'`).run();
+			const fd = openSync(temp, constants.O_RDONLY);
+			try {
+				fsyncSync(fd);
+			} finally {
+				closeSync(fd);
+			}
+			renameSync(temp, target);
+			const directory = openSync(dirname(target), constants.O_RDONLY);
+			try {
+				fsyncSync(directory);
+			} finally {
+				closeSync(directory);
+			}
+		} catch (error) {
+			rmSync(temp, { force: true });
+			throw error;
+		}
+	} finally {
+		closeQuietly(db);
+	}
+}
+
+/**
+ * Restore a consistent backup into this worktree. All accessors must be
+ * stopped; the restored database is revalidated against the worktree binding
+ * so a copy from another worktree is refused instead of granting authority.
+ */
+export function restoreKernelStore(root: string, sourcePath: string): void {
+	const canonical = canonicalRoot(root);
+	if (openStores.has(canonical))
+		throw new KernelStoreConflictError("kernel store restore requires the store to be idle");
+	const source = resolve(sourcePath);
+	if (!existsSync(source)) throw new KernelStoreConflictError("kernel store backup is missing");
+	ensureStoreDirectory(canonical);
+	const target = resolve(canonical, KERNEL_DB_RELATIVE);
+	const temp = `${target}.${randomUUID()}.restore`;
+	try {
+		copyFileSync(source, temp);
+		const fd = openSync(temp, constants.O_RDONLY);
+		try {
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		// Validate the backup copy *before* publishing it: an unreadable,
+		// incompatible or foreign-workspace backup must leave the live store and
+		// its sidecars exactly as they were.
+		const probe = openStoreFile(canonical, temp, { readOnly: true });
+		if (!probe) throw new KernelStoreConflictError("kernel store backup could not be opened");
+		closeQuietly(probe);
+	} catch (error) {
+		rmSync(temp, { force: true });
+		throw error;
+	}
+	// Only a validated backup reaches the swap. Fold the live database's write
+	// ahead log into its main file first: deleting the sidecars is otherwise a
+	// window in which committed transactions only exist in the WAL. An
+	// unreadable main file with no WAL is just a dead file: replace it. An
+	// unreadable main file that still has a WAL must stay put so those
+	// committed facts can be recovered.
+	try {
+		const walPresent = existsSync(`${target}-wal`);
+		try {
+			checkpointLiveStore(canonical, target);
+			for (const suffix of ["-wal", "-shm"]) rmSync(`${target}${suffix}`, { force: true });
+		} catch (error) {
+			if (walPresent) throw error;
+		}
+		renameSync(temp, target);
+	} catch (error) {
+		rmSync(temp, { force: true });
+		throw error;
+	}
+	const directory = openSync(dirname(target), constants.O_RDONLY);
+	try {
+		fsyncSync(directory);
+	} finally {
+		closeSync(directory);
+	}
+	const db = openStoreFile(canonical, target, {});
+	if (!db) throw new KernelStoreConflictError("restored kernel store could not be opened");
+	closeQuietly(db);
+}
+
+/**
+ * Compare two paths as the filesystem sees them: a caller-supplied target may
+ * name the same file through a symlinked prefix (macOS /var vs /private/var),
+ * so both sides are resolved before the comparison.
+ */
+function samePath(a: string, b: string): boolean {
+	const identity = (path: string): string => {
+		try {
+			return realpathSync(path);
+		} catch {
+			return resolve(path);
+		}
+	};
+	return identity(a) === identity(b);
+}
+
+/**
+ * Fold committed write-ahead-log content into the main database file so a later
+ * swap cannot lose transactions that had not reached it yet. A failure here
+ * propagates: the caller must not remove sidecars it could not checkpoint.
+ */
+function checkpointLiveStore(canonical: string, target: string): void {
+	if (!existsSync(target)) return;
+	let db: DatabaseSync;
+	try {
+		db = new DatabaseSync(target);
+	} catch (error) {
+		// The live database cannot be read, so its write-ahead log cannot be
+		// folded into it: removing the sidecars would drop committed facts.
+		throw new KernelStoreConflictError(
+			`live kernel store could not be checkpointed before restore: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	try {
+		db.exec("PRAGMA busy_timeout = 5000");
+		const result = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get() as
+			| { busy?: number | bigint; log?: number | bigint; checkpointed?: number | bigint }
+			| undefined;
+		const busy = Number(result?.busy ?? 0);
+		if (busy !== 0)
+			throw new KernelStoreConflictError(
+				"live kernel store still has an active writer; retry the restore when the store is idle",
+			);
+		const log = Number(result?.log ?? 0);
+		const checkpointed = Number(result?.checkpointed ?? 0);
+		if (log > checkpointed)
+			throw new KernelStoreConflictError(
+				"live kernel store write-ahead log could not be fully checkpointed; retry the restore",
+			);
+	} finally {
+		try {
+			db.close();
+		} catch {
+			// A close failure leaves the checkpointed file in place.
+		}
+	}
+	const fd = openSync(target, constants.O_RDONLY);
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+export function readStoreBytes(path: string): Buffer {
+	return readFileSync(path);
+}
+
+export function writeStoreBytes(path: string, bytes: Buffer): void {
+	writeFileSync(path, bytes);
+}