@kontextmind/kxm 0.7.86 → 0.7.87

package/plugins/kxm/src/cli/roles.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { DatabaseSync } from "../sqlite.ts";
+import { DatabaseSync, openReadOnlyDatabase } from "../sqlite.ts";
 import {
   DEFAULT_ROLES,
   DEFAULT_ROLE_SEATS,
@@ -20,7 +20,7 @@ import {
 import { discoverKxmProjectRoot } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { resumeWorkflowFromRuling, type WorkflowRun } from "../workflow.ts";
-import { print, type CliIo, type Runtime } from "./types.ts";
+import { print, printPlan, type CliIo, type Runtime } from "./types.ts";
 
 export interface PickCandidate {
   id: string;
@@ -192,7 +192,12 @@ export async function cmdRoleAdd(
             repoRoot: runtime.cwd,
             userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
             overwrite: options.overwrite,
+            dryRun: runtime.dryRun,
           });
+          if (runtime.dryRun) {
+            printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
+            return 0;
+          }
           print(
             runtime.io,
             runtime.json,
@@ -232,7 +237,12 @@ export async function cmdRoleAdd(
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -283,7 +293,12 @@ export async function cmdRoleRemove(
       scope,
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "role remove", roleId, ...res }, [{ action: "delete", target: res.filePath }], `remove role '${roleId}' from ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -377,7 +392,12 @@ export async function cmdRoleModify(
       scope: options.scope,
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "role modify", roleId, ...res }, [{ action: "write", target: res.filePath }], `modify role '${roleId}' in ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -482,7 +502,17 @@ export async function cmdRoleSetHost(
       scope: options.scope ?? "local",
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(
+        runtime,
+        { command: "role set-host", seatId, host, binding: result.binding, filePath: result.filePath, scope: result.scope },
+        [{ action: "write", target: result.filePath }],
+        `bind seat '${seatId}' to host '${host}'`,
+      );
+      return 0;
+    }
 
     print(
       runtime.io,
@@ -521,7 +551,12 @@ export async function cmdRoleResume(
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
   if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
     if (runtime.dryRun) {
-      print(runtime.io, runtime.json, { ok: true, command: "role resume", runId, ruling: effectiveRuling }, `would resume KXM run ${runId}`);
+      printPlan(
+        runtime,
+        { command: "role resume", runId, ruling: effectiveRuling },
+        [{ action: "request", target: `POST kxm-runtime /v1/runs/${runId}/signal (audit_escalation unblock)` }],
+        `resume KXM run ${runId}`,
+      );
       return 0;
     }
     try {
@@ -555,7 +590,7 @@ export async function cmdRoleResume(
   const dbPath = join(runtime.cwd, ".kxm", "state", "kxm.db");
   if (existsSync(dbPath)) {
     try {
-      const database = new DatabaseSync(dbPath);
+      const database = runtime.dryRun ? openReadOnlyDatabase(dbPath) : new DatabaseSync(dbPath);
       try {
         const row = database.prepare("SELECT record FROM workflow_runs WHERE id = ?").get(runId) as { record: string } | undefined;
         if (!row) {
@@ -565,6 +600,15 @@ export async function cmdRoleResume(
         const run = JSON.parse(row.record) as WorkflowRun;
         const now = new Date().toISOString();
         const resumeResult = resumeWorkflowFromRuling(run, effectiveRuling, now);
+        if (runtime.dryRun) {
+          printPlan(
+            runtime,
+            { command: "role resume", runId, stageId: resumeResult.stageId, ruling: effectiveRuling, status: resumeResult.run.status },
+            [{ action: "write", target: `${dbPath} (workflow_runs ${runId}, one workflow_journal decision)` }],
+            `resume workflow run ${runId} (stage: ${resumeResult.stageId})`,
+          );
+          return 0;
+        }
 
         database.prepare("UPDATE workflow_runs SET record = ? WHERE id = ?").run(
           JSON.stringify(resumeResult.run),

package/plugins/kxm/src/cli/system.ts

@@ -88,6 +88,7 @@ import {
 import { kxmUserStateRoot } from "../bindings.ts";
 import {
   print,
+  printPlan,
   printWorker,
   gateOf,
   type CliIo,
@@ -224,6 +225,10 @@ export async function cmdSshRun(
   options: { sudo?: boolean | undefined },
 ): Promise<number> {
   const command = commandParts.join(" ");
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "ssh run", host, remoteCommand: command, sudo: options.sudo === true }, [{ action: "ssh", target: `${host}: ${options.sudo ? "sudo " : ""}${command}` }], `run a command on ${host}`);
+    return 0;
+  }
   const receipt = executeSshRun({
     action: "command",
     host,
@@ -247,6 +252,10 @@ export async function cmdSshFile(
   options: { content?: string | undefined; read?: boolean | undefined; append?: boolean | undefined; sudo?: boolean | undefined },
 ): Promise<number> {
   const op = options.read ? "read" : (options.append ? "append" : "write");
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "ssh file", host, path: filePath, op, sudo: options.sudo === true }, [{ action: "ssh", target: `${host}: ${op} ${filePath}` }], `${op} ${filePath} on ${host}`);
+    return 0;
+  }
   const receipt = executeSshRun({
     action: "file",
     host,
@@ -269,6 +278,10 @@ export async function cmdSshFile(
 }
 
 export async function cmdSshClose(runtime: Runtime, host: string): Promise<number> {
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "ssh close", host }, [{ action: "ssh", target: `${host}: close the ControlMaster socket` }], `close the ControlMaster socket for ${host}`);
+    return 0;
+  }
   const closed = closeControlSocket(host);
   if (runtime.json) {
     print(runtime.io, runtime.json, { ok: true, closed, command: "ssh close", host }, "");
@@ -568,7 +581,11 @@ export async function cmdConfigSet(
     } catch {
       // keep string
     }
-    setKxmConfigValue(runtime.cwd, key, parsedVal, { scope });
+    const { file } = setKxmConfigValue(runtime.cwd, key, parsedVal, { scope, dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "config set", key, value: parsedVal, scope }, [{ action: "write", target: file }], `set ${key} = ${value} in ${scope} config`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,

package/plugins/kxm/src/cli/tasks.ts

@@ -11,6 +11,8 @@ import {
   getTask,
   updateTaskStatus,
   syncTaskWithTracker,
+  goalFilePath,
+  taskFilePath,
   type TaskStatus,
   type TrackerType,
 } from "../task-manager.ts";
@@ -22,8 +24,8 @@ import {
   generateStudioLayout,
 } from "../studio-layout.ts";
 import { readSessionTokenFromDisk } from "../commands.ts";
-import { print, type Runtime } from "./types.ts";
-import { cmdKxmRun } from "./project.ts";
+import { print, printPlan, type Runtime } from "./types.ts";
+import { cmdKxmRun, resolveKxmRunTarget } from "./project.ts";
 
 export async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promise<number> {
   try {
@@ -74,7 +76,11 @@ export async function cmdGoalCreate(
       area: options.area,
       successMetrics: options.metric,
       targetDate: options.targetDate,
-    });
+    }, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "goal create", goal }, [{ action: "write", target: goalFilePath(runtime.cwd, goal.id) }], `create goal ${goal.title} (the id is assigned when it is created)`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -118,7 +124,11 @@ export async function cmdTaskCreate(
       trackerSync: options.tracker && options.issue
         ? { tracker: options.tracker as TrackerType, issueKey: options.issue }
         : undefined,
-    });
+    }, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "task create", task }, [{ action: "write", target: taskFilePath(runtime.cwd, task.id) }], `create task ${task.title} [${task.status}] (the id is assigned when it is created)`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -187,6 +197,21 @@ export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<numb
       return 1;
     }
     const workflow = task.assignedWorkflow ?? "default";
+    if (runtime.dryRun) {
+      const target = resolveKxmRunTarget(runtime, workflow);
+      if (typeof target === "number") return target;
+      const started = updateTaskStatus(runtime.cwd, taskId, "in_progress", { dryRun: true });
+      printPlan(
+        runtime,
+        { command: "task run", taskId, ...target, status: started.status },
+        [
+          { action: "request", target: "POST kxm-runtime /v1/runs (starts the Runtime supervisor if it is not running)" },
+          { action: "write", target: taskFilePath(runtime.cwd, taskId) },
+        ],
+        `run workflow ${workflow} for task ${taskId}, then mark it ${started.status}`,
+      );
+      return 0;
+    }
     const exitCode = await cmdKxmRun(runtime, workflow, [task.objective]);
     if (exitCode === 0) {
       updateTaskStatus(runtime.cwd, taskId, "in_progress");
@@ -201,7 +226,11 @@ export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<numb
 
 export async function cmdTaskSync(runtime: Runtime, taskId: string): Promise<number> {
   try {
-    const synced = syncTaskWithTracker(runtime.cwd, taskId);
+    const synced = syncTaskWithTracker(runtime.cwd, taskId, { dryRun: runtime.dryRun });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "task sync", task: synced }, [{ action: "write", target: taskFilePath(runtime.cwd, taskId) }], `mark task ${taskId} synced with ${synced.trackerSync?.tracker} #${synced.trackerSync?.issueKey}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,

package/plugins/kxm/src/cli/types.ts

@@ -101,6 +101,36 @@ export function print(io: CliIo, jsonMode: boolean, payload: object, text: strin
   else io.stdout(line);
 }
 
+/** One change a command would have made had `--dry-run` not been given. */
+export interface PlannedChange {
+  action: "write" | "delete" | "move" | "request" | "ssh";
+  target: string;
+}
+
+/** The `--dry-run` answer of a mutating command: the envelope the real run
+ * prints, marked `dryRun: true`, plus every write, request, or remote step it
+ * would have taken. Nothing is written by the caller before or after this. */
+export function printPlan(
+  runtime: Runtime,
+  payload: Record<string, unknown> & { command: string },
+  planned: readonly PlannedChange[],
+  text: string,
+): void {
+  print(runtime.io, runtime.json, { ok: true, ...payload, dryRun: true, planned }, [
+    `dry run: ${text}`,
+    ...(planned.length === 0 ? ["  no changes"] : planned.map((change) => `  would ${change.action} ${change.target}`)),
+  ].join("\n"));
+}
+
+export const DRY_RUN_UNSUPPORTED = "dry_run_unsupported";
+
+/** For a command that cannot say what it would do without doing some of it:
+ * refuse under `--dry-run` instead of executing. */
+export function refuseDryRun(io: CliIo, jsonMode: boolean, command: string, reason: string): number {
+  print(io, jsonMode, { ok: false, command, dryRun: true, error: DRY_RUN_UNSUPPORTED, detail: reason }, `kxm ${command} --dry-run refused: ${reason}`);
+  return 2;
+}
+
 export function printWorker(
   runtime: Runtime,
   worker: Worker,

package/plugins/kxm/src/cli/workflows.ts

@@ -1,7 +1,7 @@
 import { createHmac, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import { DatabaseSync } from "../sqlite.ts";
+import { openReadOnlyDatabase } from "../sqlite.ts";
 import { buildRetrospective, writeRetrospective } from "../retrospective.ts";
 import { redactSecrets } from "../redact.ts";
 import { postWorkflowSignal, watchGithubChecks } from "../github-watch.ts";
@@ -24,6 +24,7 @@ import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts
 import type { WorkerOutcome } from "../envelope.ts";
 import {
   print,
+  printPlan,
   printWorker,
   gateOf,
   parseEvidencePairs,
@@ -37,7 +38,7 @@ const CLI_NAME = "kxm";
 
 export function localWorkflowSnapshot(dataPath: string, runId?: string): { runs: WorkflowRun[]; journal: WorkflowJournalEntry[] } {
   if (!existsSync(dataPath)) throw new Error("state_database_not_found");
-  const database = new DatabaseSync(dataPath, { readOnly: true });
+  const database = openReadOnlyDatabase(dataPath);
   try {
     const rows = runId
       ? database.prepare("SELECT record FROM workflow_runs WHERE id = ?").all(runId)
@@ -265,7 +266,12 @@ export async function cmdWorkflowAdd(
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "workflow add", workflowId, ...res }, [{ action: "write", target: res.filePath }], `add workflow '${workflowId}' to ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -316,7 +322,12 @@ export async function cmdWorkflowRemove(
       scope,
       repoRoot: runtime.cwd,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      dryRun: runtime.dryRun,
     });
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "workflow remove", workflowId, ...res }, [{ action: "delete", target: res.filePath }], `remove workflow '${workflowId}' from ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -373,8 +384,13 @@ export async function cmdWorkflowModify(
         scope: options.scope,
         repoRoot: runtime.cwd,
         userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+        dryRun: runtime.dryRun,
       },
     );
+    if (runtime.dryRun) {
+      printPlan(runtime, { command: "workflow modify", workflowId, ...res }, [{ action: "write", target: res.filePath }], `modify workflow '${workflowId}' in ${res.scope}`);
+      return 0;
+    }
     print(
       runtime.io,
       runtime.json,
@@ -520,7 +536,7 @@ export async function cmdSignal(runtime: Runtime, runId: string, signalKey: stri
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
   if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
     if (runtime.dryRun) {
-      printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, summary, evidence }, "would post signal to KXM run");
+      printWorker(runtime, worker, { ok: true, command: "signal", dryRun: true, runId, signalKey, status, summary, evidence }, "would post signal to KXM run");
       return 0;
     }
     const deliveryId = String(deliveryIdFlag || `cli-signal:${randomUUID()}`);
@@ -557,7 +573,7 @@ export async function cmdSignal(runtime: Runtime, runId: string, signalKey: stri
     return 2;
   }
   if (runtime.dryRun) {
-    printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, summary, evidence }, "would post signed signal");
+    printWorker(runtime, worker, { ok: true, command: "signal", dryRun: true, runId, signalKey, status, summary, evidence }, "would post signed signal");
     return 0;
   }
   const deliveryId = String(deliveryIdFlag || `cli-signal:${randomUUID()}`);

package/plugins/kxm/src/cli.ts

@@ -30,6 +30,7 @@ import { ensureKxmSupervisor, kxmRuntimeRequest } from "./runtime-supervisor.ts"
 // Submodule imports
 import {
   print,
+  refuseDryRun,
   runtimeFrom,
   redactConfiguredValues,
   type CliContext,
@@ -172,6 +173,54 @@ const USAGE_ERROR_CODES = new Set([
   "commander.optionMissingArgument",
 ]);
 
+/**
+ * Every command that answers `--dry-run` without changing anything: it only
+ * reads, or it prints the plan (`dryRun: true` plus `planned`) and stops.
+ * A command missing from this set is refused under `--dry-run` with
+ * `dry_run_unsupported` before its action runs, so a new command that forgets
+ * to check the flag fails closed instead of mutating. Keyed by command path.
+ */
+const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
+  "init", "backup", "restore", "run", "explain", "suggest", "update", "dash", "completion", "completion install",
+  "runs status", "runs drive", "runs receipt", "runs cancel", "runs list",
+  "tenant status", "models inventory-refresh", "harness list", "auth token",
+  "routes list", "routes count", "routes admit", "routes disable",
+  "runtime start", "runtime status", "runtime sync-retry", "runtime stop",
+  "trust diff", "trust check", "agent worker",
+  "session status", "session brief", "session token", "session start", "session stop",
+  "peer list", "peer send", "peer get", "peer await", "peer cancel", "peer fanout", "peer inbox", "peer reply",
+  "workflow list", "workflow get", "workflow checkpoint", "workflow record", "workflow wait", "workflow signal",
+  "workflow start", "workflow export", "workflow definitions", "workflow add", "workflow remove", "workflow modify",
+  "role list", "role get", "role add", "role remove", "role modify", "role hosts", "role set-host", "role resume",
+  "gate validate", "gate artifacts-exist", "gate degrade", "gate signal", "gate github watch",
+  "improve report",
+  "context get", "context recall", "context state", "context episode", "context promote", "context explain",
+  "context wiki-compile", "context wiki-lint",
+  "skills create", "skills evaluate", "skills promote", "skills reject", "skills list", "skills verify",
+  "memory brief", "memory note", "memory sync",
+  "routing report", "routing benchmark",
+  "ssh info", "ssh run", "ssh file", "ssh close",
+  "hub view", "hub start", "hub stop", "hub bind", "hub unbind",
+  "config get", "config set", "config list",
+  "goal create", "goal list",
+  "task create", "task list", "task get", "task run", "task sync",
+  "studio layout", "studio serve",
+]);
+
+class DryRunRefused extends Error {
+  readonly code: number;
+  constructor(code: number) {
+    super("dry_run_unsupported");
+    this.code = code;
+  }
+}
+
+function commandPath(command: Command): string {
+  const names: string[] = [];
+  for (let current: Command | null = command; current?.parent; current = current.parent) names.unshift(current.name());
+  return names.join(" ");
+}
+
 function addGlobalOptions(command: Command): Command {
   return command
     .option("--json", "Print machine-readable JSON")
@@ -331,6 +380,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     })
     .helpCommand("help", "Show help");
   addGlobalOptions(program);
+  program.hook("preAction", (_program, actionCommand) => {
+    const opts = actionCommand.optsWithGlobals() as { dryRun?: boolean; json?: boolean };
+    if (!opts.dryRun) return;
+    const path = commandPath(actionCommand);
+    if (DRY_RUN_COMMANDS.has(path)) return;
+    throw new DryRunRefused(refuseDryRun(ctx.io, Boolean(opts.json), path, "this command cannot plan without making changes; rerun without --dry-run"));
+  });
 
   program.command("init").description("Create, validate, repair, or join a KXM project")
     .option("--json", "Print machine-readable JSON")
@@ -1222,6 +1278,7 @@ export async function runCli(
     return result.code;
   } catch (error) {
     if (error instanceof CommanderError) return mapCommanderError(error);
+    if (error instanceof DryRunRefused) return error.code;
     throw error;
   }
 }

package/plugins/kxm/src/config.ts

@@ -303,8 +303,8 @@ export function setKxmConfigValue(
   repoRoot: string,
   keyPath: string,
   value: unknown,
-  options: { scope?: "user" | "project"; userConfigDir?: string } = {},
-): void {
+  options: { scope?: "user" | "project"; userConfigDir?: string; dryRun?: boolean } = {},
+): { file: string } {
   const targetFile = kxmConfigFileForScope(repoRoot, options.scope ?? "project", options.userConfigDir);
   const existing = readConfigFile(targetFile);
   const parts = configKeyParts(keyPath);
@@ -317,7 +317,8 @@ export function setKxmConfigValue(
     cursor = cursor[p] as Record<string, unknown>;
   }
   cursor[parts[parts.length - 1]!] = value;
-  writeConfigFile(targetFile, existing);
+  if (!options.dryRun) writeConfigFile(targetFile, existing);
+  return { file: targetFile };
 }
 
 /**

package/plugins/kxm/src/database.ts

@@ -649,11 +649,20 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
   return stores;
 }
 
-export function createBackup(options: {
+export interface BackupPlan {
+  projectRoot: string;
+  outDir: string;
+  createdAt: string;
+  stores: Array<{ storeId: string; sourcePath: string; backupFile: string }>;
+}
+
+/** Which stores a backup would copy and where, without opening any of them.
+ * Opening a source for backup checkpoints its WAL, so the plan stays at paths. */
+export function planBackup(options: {
   projectRoot?: string;
   outDir?: string;
   hubDataPath?: string;
-} = {}): { manifest: BackupManifest; outDir: string } {
+} = {}): BackupPlan {
   const projectRoot = options.projectRoot ? resolve(options.projectRoot) : process.cwd();
   const stores = discoverProjectStores(projectRoot, {
     ...(options.hubDataPath !== undefined ? { hubDataPath: options.hubDataPath } : {}),
@@ -663,35 +672,43 @@ export function createBackup(options: {
     throw databaseError("backup_no_stores", projectRoot, "no existing SQLite stores found to backup");
   }
 
-  const now = new Date();
-  const timestamp = now.toISOString().replace(/[:.]/g, "-");
-  const backupId = `bk_${randomBytes(8).toString("hex")}`;
+  const createdAt = new Date().toISOString();
+  const timestamp = createdAt.replace(/[:.]/g, "-");
   const outDir = options.outDir ? resolve(options.outDir) : join(projectRoot, ".kxm", "backups", `backup-${timestamp}`);
-
-  if (!existsSync(outDir)) {
-    mkdirSync(outDir, { recursive: true, mode: 0o700 });
-  }
-
-  const backedUpStores: BackupStoreRecord[] = [];
   const usedFilenames = new Set<string>();
-
-  for (const store of stores) {
+  const planned = stores.map((store) => {
     let filename = basename(store.sourcePath);
     if (usedFilenames.has(filename)) {
       const sanitizedId = store.storeId.replace(/[^a-zA-Z0-9_.-]/g, "_");
       filename = `${sanitizedId}-${filename}`;
     }
     usedFilenames.add(filename);
+    return { storeId: store.storeId, sourcePath: store.sourcePath, backupFile: filename };
+  });
+  return { projectRoot, outDir, createdAt, stores: planned };
+}
+
+export function createBackup(options: {
+  projectRoot?: string;
+  outDir?: string;
+  hubDataPath?: string;
+} = {}): { manifest: BackupManifest; outDir: string } {
+  const { projectRoot, outDir, createdAt, stores } = planBackup(options);
+  const backupId = `bk_${randomBytes(8).toString("hex")}`;
 
-    const targetFile = join(outDir, filename);
-    const record = backupDatabaseFile(store.sourcePath, targetFile, store.storeId);
-    backedUpStores.push(record);
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true, mode: 0o700 });
+  }
+
+  const backedUpStores: BackupStoreRecord[] = [];
+  for (const store of stores) {
+    backedUpStores.push(backupDatabaseFile(store.sourcePath, join(outDir, store.backupFile), store.storeId));
   }
 
   const manifest: BackupManifest = {
     schema: "kxm.backup-manifest.v1",
     backupId,
-    createdAt: now.toISOString(),
+    createdAt,
     projectRoot,
     stores: backedUpStores,
   };
@@ -707,10 +724,19 @@ export function createBackup(options: {
   return { manifest, outDir };
 }
 
-export function restoreBackup(
+export interface RestorePlan {
+  manifestPath: string;
+  backupId: string;
+  stores: Array<{ storeId: string; backupFilePath: string; targetPath: string; schemaVersion: number; maxSupportedVersion: number }>;
+}
+
+/** Everything restore checks before it overwrites anything: the manifest, each
+ * backup file's digest, and each store's schema against this build's ceiling
+ * (from the manifest). Reads files; opens no database. */
+export function planRestore(
   manifestPathOrDir: string,
   options: { projectRoot?: string } = {},
-): RestoreResult {
+): RestorePlan {
   let manifestPath = resolve(manifestPathOrDir);
   const stat = lstatSync(manifestPath, { throwIfNoEntry: false });
   if (!stat) {
@@ -737,8 +763,7 @@ export function restoreBackup(
     throw databaseError("restore_manifest_invalid", manifestPath, "manifest is not a valid kxm.backup-manifest.v1 document");
   }
 
-  const restoredStores: RestoreStoreRecord[] = [];
-
+  const stores: RestorePlan["stores"] = [];
   for (const store of manifest.stores) {
     const backupFilePath = join(manifestDir, store.backupFile);
     if (!existsSync(backupFilePath)) {
@@ -754,27 +779,41 @@ export function restoreBackup(
       );
     }
 
-    const maxSupported = kxmBackupCeiling(store.storeId);
+    const maxSupportedVersion = kxmBackupCeiling(store.storeId);
+    if (store.schemaVersion > maxSupportedVersion) {
+      throw databaseError(
+        "runtime_schema_newer",
+        backupFilePath,
+        `backup store ${store.storeId} schema version ${store.schemaVersion} is newer than supported maximum ${maxSupportedVersion}`,
+      );
+    }
 
     let targetPath = store.sourcePath;
     if (options.projectRoot && manifest.projectRoot && targetPath.startsWith(manifest.projectRoot)) {
       const rel = targetPath.slice(manifest.projectRoot.length).replace(/^[\\/]+/, "");
       targetPath = join(resolve(options.projectRoot), rel);
     }
-
-    const result = restoreDatabaseFile(
-      backupFilePath,
-      targetPath,
-      store.storeId,
-      store.schemaVersion,
-      maxSupported,
-    );
-    restoredStores.push(result);
+    stores.push({ storeId: store.storeId, backupFilePath, targetPath, schemaVersion: store.schemaVersion, maxSupportedVersion });
   }
 
+  return { manifestPath, backupId: manifest.backupId, stores };
+}
+
+export function restoreBackup(
+  manifestPathOrDir: string,
+  options: { projectRoot?: string } = {},
+): RestoreResult {
+  const plan = planRestore(manifestPathOrDir, options);
+  const restoredStores = plan.stores.map((store) => restoreDatabaseFile(
+    store.backupFilePath,
+    store.targetPath,
+    store.storeId,
+    store.schemaVersion,
+    store.maxSupportedVersion,
+  ));
   return {
-    manifestPath,
-    backupId: manifest.backupId,
+    manifestPath: plan.manifestPath,
+    backupId: plan.backupId,
     restoredStores,
   };
 }