mirror-mind 0.0.1 → 0.32.1

package/ts/src/frontDoor/extensionCatalogRoute.ts

@@ -0,0 +1,252 @@
+// Front-door route for the extension catalog family (CV22.DS7.TS4 plateau 7):
+// `extensions`, `ext`, `list extensions|all`, and `inspect`'s four TS4 targets.
+//
+// The route is thin on purpose. Every byte it prints was decided by
+// `catalogCommands.ts` or `inspectLedger.ts`, both pure and graded by their own
+// corpora. What happens here is the part a corpus cannot cover: choosing a read
+// or a write handle, composing `list all` from three ported renderers,
+// executing a dispatch decision in a real process, and reporting a LEAF NAME to
+// the front-door log.
+//
+// Two rules shape it:
+//
+//   * **Redaction.** `detail` carries the leaf and nothing else. An extension
+//     subcommand's argv routinely holds account ids, campaign names, and folder
+//     paths — the security-engineer's plan-stage requirement — so a dispatch
+//     logs `leaf=<id>` and never what followed it.
+//   * **No handle while the host runs.** `ext <id> <subcommand>` reaches the
+//     compat host, which opens the database itself, exactly as Python's
+//     dispatcher does. So the dispatch decision is taken WITHOUT a handle and
+//     the host is spawned with none open: two writers on one file is a
+//     SQLITE_BUSY this route would be creating for itself.
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import type { BindingDeps } from "#extensions/bindings.ts";
+import type { RenderedCommand } from "#extensions/catalog.ts";
+import {
+  type CatalogContext,
+  type ExtWriteContext,
+  runExtCommand,
+  runExtensionsCommand,
+  runInspectCommand,
+  runListCommand,
+  UnsupportedCatalogCommandError,
+} from "#extensions/catalogCommands.ts";
+import {
+  type ExtensionDispatch,
+  isExtensionDispatch,
+  runExtensionSubcommand,
+} from "#extensions/dispatch.ts";
+import { listJourneysForListCommand } from "#identity/journeyListing.ts";
+import { listPersonas } from "#identity/personaListing.ts";
+import { runInspectEmbeddingProvenance, runInspectLlmCalls } from "#observability/inspectLedger.ts";
+import { renderListJourneys, renderListPersonas } from "./render/list.ts";
+
+export interface ExtensionRouteOutcome {
+  exitCode: number;
+  /** Leaf names only. Never an argument value. */
+  detail: string;
+}
+
+export interface ExtensionRouteDeps {
+  mirrorHome: string;
+  databasePath: string;
+  deps: BindingDeps;
+  /**
+   * The database seams, narrowed to an EXIT CODE on purpose: every caller here
+   * answers a command, and a generic `<T>` would let a future branch smuggle a
+   * value out of a handle that is already closed by the time it is read.
+   */
+  withReadOnlyDatabase: (run: (db: Database) => number) => number;
+  withWritableDatabase: (
+    run: (db: WritableDatabase) => Promise<number> | number,
+  ) => Promise<number>;
+  environment?: NodeJS.ProcessEnv;
+}
+
+/** The `extensions` verbs that need a writable handle; the rest read. */
+const EXTENSIONS_WRITE_VERBS = new Set([
+  "sync",
+  "install",
+  "uninstall",
+  "expose-claude",
+  "clean-claude",
+]);
+/** The `ext` built-in verbs that write. `bindings` reads; the rest dispatch. */
+const EXT_WRITE_VERBS = new Set(["bind", "unbind", "migrate"]);
+const EXT_READ_VERBS = new Set(["bindings"]);
+const EXT_HELP_HEADS = new Set(["list", "--help", "-h", "help"]);
+
+/** A failed `register(api)` during install: Python's traceback, one TS line. */
+
+function emit(rendered: RenderedCommand): number {
+  if (rendered.stdout) process.stdout.write(rendered.stdout);
+  if (rendered.stderr) process.stderr.write(rendered.stderr);
+  return rendered.exitCode;
+}
+
+/** The dispatcher's own `--mirror-home` consumption, so the verb is the verb. */
+function extArgs(argv: readonly string[]): string[] {
+  const args: string[] = [];
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index] as string;
+    if (token === "--mirror-home" && argv[index + 1] !== undefined) {
+      index += 1;
+      continue;
+    }
+    args.push(token);
+  }
+  return args;
+}
+
+/**
+ * The leaf name for the front-door log.
+ *
+ * `extensions install ext-google-ads` logs `leaf=install`: the verb is the
+ * leaf and the id is an argument. `ext google-ads campaigns --account 1234`
+ * logs `leaf=google-ads` — the installed extension that answered — because the
+ * subcommand's arguments are where account ids and campaign names live.
+ */
+export function leafFor(argv: readonly string[]): string {
+  const command = argv[0] ?? "";
+  if (command === "extensions") return firstPositional(argv.slice(1)) ?? "list";
+  if (command === "inspect") return firstPositional(argv.slice(1)) ?? "(none)";
+  if (command === "list") return firstPositional(argv.slice(1)) ?? "all";
+  if (command === "ext") {
+    const args = extArgs(argv);
+    const head = args[0];
+    if (head === undefined) return "(none)";
+    if (EXT_HELP_HEADS.has(head)) return head;
+    const verb = args[1];
+    if (verb !== undefined && (EXT_WRITE_VERBS.has(verb) || EXT_READ_VERBS.has(verb))) {
+      return `${head}/${verb}`;
+    }
+    return head;
+  }
+  return command;
+}
+
+function firstPositional(args: readonly string[]): string | null {
+  const valued = new Set(["--mirror-home", "--extensions-root", "--runtime", "--target-root"]);
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index] as string;
+    if (valued.has(token)) {
+      index += 1;
+      continue;
+    }
+    if (!token.startsWith("--")) return token;
+  }
+  return null;
+}
+
+function readContextFor(route: ExtensionRouteDeps): CatalogContext {
+  return { mirrorHome: route.mirrorHome };
+}
+
+function dispatchOptions(route: ExtensionRouteDeps) {
+  return {
+    databasePath: route.databasePath,
+    ...(route.environment ? { environment: route.environment } : {}),
+  };
+}
+
+function writeContextFor(route: ExtensionRouteDeps, db: WritableDatabase): ExtWriteContext {
+  return { mirrorHome: route.mirrorHome, db, deps: route.deps };
+}
+
+export async function runExtensionCatalogRoute(
+  argv: readonly string[],
+  route: ExtensionRouteDeps,
+): Promise<ExtensionRouteOutcome> {
+  const command = argv[0] ?? "";
+  const args = argv.slice(1);
+  const detail = `leaf=${leafFor(argv)}`;
+
+  // No translation layer here any more: `install` no longer imports extension
+  // code, so the one failure class this route used to catch -- a `register(api)`
+  // raising inside the Python host -- cannot occur. Manifest and migration
+  // failures keep the paths they already had.
+  if (command === "extensions") {
+    const verb = firstPositional(args) ?? "list";
+    if (!EXTENSIONS_WRITE_VERBS.has(verb)) {
+      return { exitCode: emit(runExtensionsCommand(readContextFor(route), args)), detail };
+    }
+    const exitCode = await route.withWritableDatabase((db) =>
+      emit(runExtensionsCommand(writeContextFor(route, db), args)),
+    );
+    return { exitCode, detail };
+  }
+
+  if (command === "inspect") return { exitCode: runInspect(args, route), detail };
+  if (command === "list") return { exitCode: runList(args, route), detail };
+  if (command === "ext") return { exitCode: await runExt(argv, route), detail };
+
+  throw new UnsupportedCatalogCommandError(`extension catalog route: ${command}`);
+}
+
+/**
+ * `inspect`'s four TS4 targets, dispatched by target because they do not share
+ * a refusal class: the catalog pair prints usage on stdout at exit 1, and the
+ * ledger pair is argparse and exits 2 on stderr. One command, two classes.
+ */
+function runInspect(args: readonly string[], route: ExtensionRouteDeps): number {
+  const target = firstPositional(args);
+  if (target === "llm-calls" || target === "embedding-provenance") {
+    return route.withReadOnlyDatabase((db) => {
+      const result =
+        target === "llm-calls"
+          ? runInspectLlmCalls(db, args.slice(1))
+          : runInspectEmbeddingProvenance(db, args.slice(1));
+      return emit(result);
+    });
+  }
+  return emit(runInspectCommand(readContextFor(route), args));
+}
+
+/**
+ * `list`, composed.
+ *
+ * `all` prints personas, journeys, and extensions in that order with a blank
+ * line between blocks — three renderers from two stories, which is why this
+ * composition lives at the front door rather than inside either of them.
+ */
+function runList(args: readonly string[], route: ExtensionRouteDeps): number {
+  const target = firstPositional(args) ?? "all";
+  const verbose = args.includes("--verbose");
+  if (target === "extensions") return emit(runListCommand(readContextFor(route), args));
+
+  return route.withReadOnlyDatabase((db) => {
+    process.stdout.write(renderListPersonas(listPersonas(db), verbose));
+    process.stdout.write("\n");
+    process.stdout.write(renderListJourneys(listJourneysForListCommand(db)));
+    process.stdout.write("\n");
+    // The extension block of `all` is `list extensions` with the same options.
+    return emit(runListCommand(readContextFor(route), ["extensions", ...args.slice(1)]));
+  });
+}
+
+/**
+ * `ext`, in three shapes.
+ *
+ * The built-in verbs take a handle (write or read). The dispatch takes NONE:
+ * the decision is pure, and the host that executes it opens the database
+ * itself, exactly as Python's dispatcher does.
+ */
+async function runExt(argv: readonly string[], route: ExtensionRouteDeps): Promise<number> {
+  const args = extArgs(argv);
+  const verb = args[1];
+  if (verb !== undefined && EXT_WRITE_VERBS.has(verb)) {
+    return route.withWritableDatabase((db) =>
+      emit(runExtCommand(writeContextFor(route, db), argv.slice(1)) as RenderedCommand),
+    );
+  }
+  if (verb !== undefined && EXT_READ_VERBS.has(verb)) {
+    return route.withWritableDatabase((db) =>
+      emit(runExtCommand(writeContextFor(route, db), argv.slice(1)) as RenderedCommand),
+    );
+  }
+
+  const answer = runExtCommand(readContextFor(route), argv.slice(1));
+  if (!isExtensionDispatch(answer)) return emit(answer);
+  return runExtensionSubcommand(answer as ExtensionDispatch, dispatchOptions(route));
+}

package/ts/src/frontDoor/frontDoorLog.ts

@@ -0,0 +1,57 @@
+// Durable, redacted observability for the front door (CR026).
+//
+// The front door is a production write path that previously left no trace of
+// backup failures, guard refusals, SQLITE_BUSY, or resolution problems. This
+// appends a metadata-only line per invocation to `<mirror home>/front-door.log`
+// (beside `mirror-logger.log`), under a fail-quietly contract: logging never
+// throws and never blocks the user command.
+//
+// Redaction is structural (RS005/CR033): a `FrontDoorLogEntry` carries only the
+// command name, the route, the exit code, and a short error CATEGORY — never
+// argv payloads (`--content`) or stdin. Callers must not put argument values in
+// `detail`.
+
+import { appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface FrontDoorLogEntry {
+  command: string | null;
+  /**
+   * `retired` (CV22.DS10.TS4) is a route like the other two: the front door
+   * answered, and the answer was that the surface no longer exists. It is
+   * logged so "my command disappeared" stays answerable from the log after the
+   * story that removed it is history.
+   *
+   * `usage` (CV22.DS10.TS5) is the front door's answer for a name it does not
+   * know -- the answer Python owned until TS5 deleted it.
+   */
+  route: "ts" | "retired" | "usage";
+  exitCode: number;
+  /** A short, content-free note or error category. Never argument values. */
+  detail?: string;
+}
+
+/** The log path for a resolved database path (sibling of the DB). */
+export function frontDoorLogPath(dbPath: string): string {
+  return join(dirname(dbPath), "front-door.log");
+}
+
+/** Append one redacted line. Fail-quietly: any error is swallowed. */
+export function logFrontDoor(logPath: string | null, entry: FrontDoorLogEntry): void {
+  if (!logPath) return;
+  try {
+    const level = entry.exitCode === 0 ? "INFO" : "ERROR";
+    const detail = entry.detail ? entry.detail.replace(/[\r\n\t]+/g, " ") : "";
+    const line = [
+      new Date().toISOString(),
+      level,
+      entry.command ?? "(none)",
+      entry.route,
+      `exit=${entry.exitCode}`,
+      detail,
+    ].join("\t");
+    appendFileSync(logPath, `${line}\n`);
+  } catch {
+    // Logging must never break the user command (fail-quietly contract).
+  }
+}

package/ts/src/frontDoor/identityWrite.ts

@@ -0,0 +1,36 @@
+// Front-door `identity set` write handler (US4).
+//
+// `applyIdentitySet` is the testable core of routing `identity set` to the TS
+// core: it decides the created/updated verb from the pre-write state and applies
+// the ported `setIdentity` (US3) with a generated id/now. The pre-write backup
+// that `openDatabaseForWrite` requires lives in `liveBackup.ts`. Only
+// `identity set` routes here directly. Since CV22.DS7.TS4 plateau 6,
+// `identity edit` shares this write: it drives $EDITOR, then applies the buffer
+// through `applyIdentitySet` so both commands report the same created/updated
+// verb from the same pre-write check.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { setIdentity } from "#identity/setIdentity.ts";
+
+export interface IdentitySetOutcome {
+  action: "created" | "updated";
+  layer: string;
+  key: string;
+}
+
+/** Apply `identity set`: upsert content (metadata inherited), reporting the verb. */
+export function applyIdentitySet(
+  db: WritableDatabase,
+  params: { layer: string; key: string; content: string; id: string; nowIso: string },
+): IdentitySetOutcome {
+  const existing =
+    db
+      .prepare("SELECT id FROM identity WHERE layer = ? AND key = ?")
+      .get(params.layer, params.key) !== undefined;
+  setIdentity(
+    db,
+    { id: params.id, layer: params.layer, key: params.key, content: params.content },
+    params.nowIso,
+  );
+  return { action: existing ? "updated" : "created", layer: params.layer, key: params.key };
+}

package/ts/src/frontDoor/journeyWriteRoute.ts

@@ -0,0 +1,26 @@
+// Front-door `journey set-path` write handler (US5).
+//
+// applyJourneySetPath is the testable core of routing `journey set-path` to the TS
+// core: it normalizes the path the way Python does, then delegates to the ported
+// US2 setProjectPath over the US4 live-write seam. setProjectPath throws when the
+// journey does not exist; the cli wrapper maps that to Python's not-found output.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { setProjectPath } from "#journey/journeyWrite.ts";
+import { normalizeProjectPath } from "#util/paths.ts";
+
+/**
+ * Apply `journey set-path`: normalize `rawPath` (expanduser + resolve, matching
+ * Python), write it into the journey's `project_path` metadata via setProjectPath,
+ * and return the resolved path. Throws `journey not found: <slug>` when absent.
+ */
+export function applyJourneySetPath(
+  db: WritableDatabase,
+  slug: string,
+  rawPath: string,
+  nowIso: string,
+): string {
+  const resolved = normalizeProjectPath(rawPath);
+  setProjectPath(db, slug, resolved, nowIso);
+  return resolved;
+}

package/ts/src/frontDoor/lifecycleWriteRoute.ts

@@ -0,0 +1,110 @@
+// The ES-001 metadata-lifecycle WRITE faces at the front door
+// (CV22.DS7.TS4 plateau 7).
+//
+// `conversations --metadata-lifecycle-apply <id> [--title/--summary/--tag]` and
+// `--metadata-lifecycle-demo`. Both print `json.dumps(report, ensure_ascii=
+// False, indent=2)`, so the rendering is `JSON.stringify(report, null, 2)` plus
+// the newline `print` adds, and key ORDER is part of those bytes.
+//
+// The demo builds its own throwaway world. Python's is `sqlite3.connect(
+// ":memory:")` with the schema applied; here it is a bootstrapped temp file
+// removed on the way out, because `node:sqlite`'s in-memory handle cannot be
+// given the migration ledger the bootstrap writes. Either way the claim it
+// prints — `uses_production_data: false` — stays literally true: the caller's
+// database is opened, never written, and never read by the demo.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LifecycleFaceError } from "#conversation/lifecycleFaces.ts";
+import {
+  applyMetadataLifecycle,
+  type DemoSeed,
+  metadataLifecycleDemoReport,
+  writeTitle,
+} from "#conversation/lifecycleWrites.ts";
+import { bootstrapDatabase } from "#db/bootstrap.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+
+/** Python's `print(json.dumps(report, ensure_ascii=False, indent=2))`. */
+function printReport(report: unknown): number {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  return 0;
+}
+
+function optionValue(argv: readonly string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+/** `--tag` is singular and REPEATABLE (`dest="tags"`, `action="append"`). */
+function tagValues(argv: readonly string[]): string[] | undefined {
+  const tags: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== "--tag") continue;
+    const value = argv[index + 1];
+    if (value !== undefined) tags.push(value);
+  }
+  return tags.length > 0 ? tags : undefined;
+}
+
+export function runLifecycleWriteRoute(db: WritableDatabase, args: readonly string[]): number {
+  if (args.includes("--metadata-lifecycle-demo")) return runDemo();
+
+  const conversationId = optionValue(args, "--metadata-lifecycle-apply");
+  if (conversationId === undefined) {
+    console.error("Mirror TS front door: --metadata-lifecycle-apply requires a conversation id");
+    return 2;
+  }
+  const title = optionValue(args, "--title");
+  const summary = optionValue(args, "--summary");
+  const tags = tagValues(args);
+  try {
+    return printReport(
+      applyMetadataLifecycle(db, conversationId, {
+        ...(title !== undefined ? { title } : {}),
+        ...(summary !== undefined ? { summary } : {}),
+        ...(tags !== undefined ? { tags } : {}),
+      }),
+    );
+  } catch (error) {
+    if (!(error instanceof LifecycleFaceError)) throw error;
+    // Python raises ValueError and the traceback escapes: same exit code, same
+    // stream, one line.
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function runDemo(): number {
+  const root = mkdtempSync(join(tmpdir(), "mirror-lifecycle-demo-"));
+  try {
+    const db = bootstrapDatabase(join(root, "memory_test.db"));
+    try {
+      const seed: DemoSeed = {
+        startConversation: (interfaceName, title) => {
+          const id = newId();
+          db.prepare(
+            "INSERT INTO conversations (id, interface, title, started_at) VALUES (?, ?, ?, ?)",
+          ).run(id, interfaceName, title ?? null, nowIso());
+          return id;
+        },
+        addMessage: (conversationId, role, content) => {
+          db.prepare(
+            "INSERT INTO messages (id, conversation_id, role, content, created_at) " +
+              "VALUES (?, ?, ?, ?, ?)",
+          ).run(newId(), conversationId, role, content, nowIso());
+        },
+        setProvisionalTitle: (conversationId, title) =>
+          writeTitle(db, conversationId, title, "provisional"),
+        updateTitle: (conversationId, title) => writeTitle(db, conversationId, title, "manual"),
+      };
+      return printReport(metadataLifecycleDemoReport(db, seed));
+    } finally {
+      db.close();
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/ts/src/frontDoor/liveBackup.ts

@@ -0,0 +1,100 @@
+// Pre-write backup and restore for the front door's sanctioned live writes.
+//
+// Every routed live write takes a fresh snapshot first; `openDatabaseForWrite`
+// refuses to open without a hash-verified record of it. The snapshot is taken
+// with `VACUUM INTO` (WAL-correct — see `snapshotDatabaseTo`), stored under the
+// mirror home's `backups/` directory (the same convention the Python backup
+// tooling uses), and permission-tightened to owner-only.
+//
+// Overwrite-window semantics, stated plainly: the backup file has a FIXED name
+// and is replaced before EVERY write, so it always holds the state immediately
+// before the most recent routed write — and nothing older. If a write corrupts
+// data and another routed write runs before anyone notices, the corrupted
+// state becomes the backed-up state. The backup is a last-write undo, not an
+// archive; scheduled archives remain `mm-backup`'s job.
+//
+// Concurrent writers (CV22.DS10.TS5, finding F21). Until F21 every writer
+// removed the fixed file and recreated it in place with `VACUUM INTO`, with no
+// coordination. Two writers at the same instant broke each other: the second
+// `VACUUM INTO` found the tables the first was still creating ("table
+// conversations already exists"), or one removed the file the other was still
+// writing ("disk I/O error"), and the losing write was aborted. Claude Code
+// runs its two prompt hooks at once and both write, so the Navigator walk lost
+// two injections in three prompts; Pi had been losing turns in daily use.
+//
+// So each writer now snapshots into a staging file of its own, the gate
+// verifies THAT file -- which no other writer can touch -- and only then is it
+// promoted to the fixed name by an atomic rename. The fixed name keeps its
+// meaning (the state before the most recently promoted write) and can no
+// longer be observed half-written. Under true concurrency "the most recent
+// write" is whichever promoted last; nothing stronger was ever true.
+//
+// One residue remains possible: a writer KILLED between its snapshot and its
+// rename leaves its staging file, the size of the database. Each write sweeps
+// those before taking its own -- a staging file whose process no longer runs
+// and which is older than any snapshot takes (TS5 handoff review, finding N4).
+
+import { chmodSync, copyFileSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stagingToken, sweepAbandoned } from "#backup/staging.ts";
+import { type BackupRecord, requireBackup, sha256File } from "#db/backupGate.ts";
+import { openDatabaseForWrite, snapshotDatabaseTo, type WritableDatabase } from "#db/database.ts";
+
+const BACKUP_DIR_NAME = "backups";
+const BACKUP_FILE_NAME = "frontdoor-pre-write-backup.db";
+
+/** Where the pre-write backup for a given live database lives. */
+export function backupPathFor(dbPath: string): string {
+  return join(dirname(dbPath), BACKUP_DIR_NAME, BACKUP_FILE_NAME);
+}
+
+/** The name a writer gives its staging file: `<fixed name>.<pid>-<12 hex>.staging`. */
+const STAGING_FILE = /^frontdoor-pre-write-backup\.db\.(\d+)-[0-9a-f]{12}\.staging$/;
+
+/**
+ * Open the live database for ONE routed write, behind a verified pre-write
+ * snapshot. The only sanctioned way to open a live `memory.db` for writing.
+ *
+ * 1. Snapshot into a staging file unique to this process and call
+ *    (WAL-correct via `VACUUM INTO`; owner-only: 0700 dir, 0600 file).
+ * 2. The backup gate verifies the staging file's hash, and the database opens.
+ * 3. The staging file is promoted to the fixed name by an atomic rename.
+ *
+ * A failure at any step aborts the write and removes the staging file, so a
+ * failed snapshot never leaves a half-written file under the fixed name. A
+ * staging file a KILLED writer left behind is swept first (finding N4).
+ */
+export function openLiveWriteDatabase(dbPath: string): WritableDatabase {
+  const backupPath = backupPathFor(dbPath);
+  mkdirSync(dirname(backupPath), { recursive: true, mode: 0o700 });
+  sweepAbandoned(dirname(backupPath), STAGING_FILE);
+  const staging = `${backupPath}.${stagingToken()}.staging`;
+  let db: WritableDatabase | null = null;
+  try {
+    snapshotDatabaseTo(dbPath, staging);
+    chmodSync(staging, 0o600);
+    db = openDatabaseForWrite(dbPath, { path: staging, sha256: sha256File(staging) });
+    renameSync(staging, backupPath);
+    return db;
+  } catch (error) {
+    db?.close();
+    throw error;
+  } finally {
+    // A no-op after the rename; the cleanup when anything before it failed.
+    rmSync(staging, { force: true });
+  }
+}
+
+/**
+ * Restore the live database from a verified pre-write backup: re-verify the
+ * record's hash, copy the snapshot over the live file, and remove stale
+ * `-wal`/`-shm` sidecars so SQLite cannot replay post-backup pages over the
+ * restored state. Callers must ensure nothing holds the database open.
+ */
+export function restoreFromBackup(backup: BackupRecord, dbPath: string): void {
+  requireBackup(backup);
+  copyFileSync(backup.path, dbPath);
+  rmSync(`${dbPath}-wal`, { force: true });
+  rmSync(`${dbPath}-shm`, { force: true });
+  chmodSync(dbPath, 0o600);
+}