@kontextmind/kxm 0.7.86 → 0.7.88

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/context/providers.ts

@@ -44,6 +44,10 @@ export interface StateChangeProposal {
   confidence: ContextItem["confidence"];
   evidenceRefs: string[];
   proposedBy: string;
+  /** Origin of the credential the hub verified for the proposer: an agent
+   * key is `peer` (evidence at most), the administrative token `human`.
+   * Never inferred from `proposedBy`, which is a label, not a credential. */
+  origin: "peer" | "human";
   supersedes?: string[];
 }
 

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,
   };
 }

package/plugins/kxm/src/hub.ts

@@ -601,9 +601,12 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
 
   /** Context callers authenticate either as a registered agent (project-
    * scoped to their own project) or with the administrative token (single
-   * explicit project scope per request). Returns the validated project and
-   * a stable caller identity for provenance. */
-  function contextCallerProject(request: IncomingMessage, requested: unknown): { project: string; caller: string } {
+   * explicit project scope per request). Returns the validated project, a
+   * stable caller identity for provenance, and which credential proved it. */
+  function contextCallerProject(
+    request: IncomingMessage,
+    requested: unknown,
+  ): { project: string; caller: string; credential: "agent" | "admin" } {
     const project = requireString(requested, "project", { max: 200 });
     const agentHeader = request.headers["x-kxm-agent-id"];
     if (typeof agentHeader === "string" && agentHeader.trim()) {
@@ -612,14 +615,14 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       if (agent.project !== project) {
         throw new ProtocolError(403, "context requests are limited to the agent's project", "context_isolation_violation");
       }
-      return { project, caller: agent.id };
+      return { project, caller: agent.id, credential: "agent" };
     }
     requireAdminAuth(request);
     const callerHeader = request.headers["x-kxm-caller-id"];
     const caller = typeof callerHeader === "string" && callerHeader.trim()
       ? callerHeader.trim()
       : "kxm-admin";
-    return { project, caller };
+    return { project, caller, credential: "admin" };
   }
 
   function requireAdminAuth(request: IncomingMessage): void {
@@ -1829,7 +1832,21 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       const contextStateProposeMatch = url.pathname.match(/^\/v1\/context\/state\/propose$/);
       if (method === "POST" && contextStateProposeMatch) {
         const body = await readJson(request);
-        const { project: callerProject, caller: callerId } = contextCallerProject(request, body.project);
+        const { project: callerProject, caller: callerId, credential } = contextCallerProject(request, body.project);
+        // Origin follows the credential, never a name: an agent key proposes as
+        // a peer, capped at evidence by the grant floor. Human origin can claim
+        // policy, so it takes the configured administrative token with no
+        // loopback bypass, as promotion does.
+        if (credential === "admin") requireConfiguredAdminAuth(request, "human-origin state proposals");
+        if (body.proposedBy !== undefined && body.proposedBy !== callerId) {
+          logger({ event: "security_alert", alert: "state_proposer_mismatch", project: callerProject, callerId, credential });
+          throw new ProtocolError(
+            403,
+            "proposedBy must name the authenticated caller",
+            "state_proposer_mismatch",
+          );
+        }
+        const origin = credential === "agent" ? "peer" : "human";
         const proposalId = await stateProvider.propose({
           schema: "kxm.state-change-proposal.v1",
           project: callerProject,
@@ -1838,11 +1855,12 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           authority: parseContextAuthority(body.authority),
           confidence: parseContextConfidence(body.confidence),
           evidenceRefs: boundedStringList(body.evidenceRefs, "evidenceRefs", 32),
-          proposedBy: (typeof body.proposedBy === "string" && body.proposedBy.trim()) ? body.proposedBy.trim() : callerId,
+          proposedBy: callerId,
+          origin,
         });
         counters.contextRequests += 1;
         publishOps(callerProject, "workflows");
-        logger({ event: "context_state_proposed", project: callerProject, proposalId, proposedBy: callerId });
+        logger({ event: "context_state_proposed", project: callerProject, proposalId, proposedBy: callerId, origin });
         json(response, 201, { proposalId });
         return;
       }

package/plugins/kxm/src/local-snapshot.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
-import { DatabaseSync } from "./sqlite.ts";
+import { DatabaseSync, openReadOnlyDatabase } from "./sqlite.ts";
 import type { AgentIdentity, AgentRecord, MessageRecord } from "./protocol.ts";
 import type { WorkflowRun } from "./workflow.ts";
 import { readRoutingRecords } from "./telemetry.ts";
@@ -250,7 +250,7 @@ export function loadLocalMeshSnapshot(
   let plans: MeshTuiPlan[] = [];
   if (existsSync(dataPath)) {
     hasLegacy = true;
-    const database = new DatabaseSync(dataPath, { readOnly: true });
+    const database = openReadOnlyDatabase(dataPath);
     try {
       database.exec("PRAGMA busy_timeout = 5000");
       // Stored rows carry identity only. Presence is derived here against the
@@ -287,7 +287,7 @@ export function loadLocalMeshSnapshot(
     if (existsSync(registryDbPath)) {
       hasKxm = true;
       try {
-        const regDb = new DatabaseSync(registryDbPath, { readOnly: true });
+        const regDb = openReadOnlyDatabase(registryDbPath);
         try {
           regDb.exec("PRAGMA busy_timeout = 5000");
           const pRows = regDb.prepare("SELECT project_key FROM projects").all() as Array<{ project_key: string }>;
@@ -315,7 +315,7 @@ export function loadLocalMeshSnapshot(
       if (existsSync(eventDbPath)) {
         hasKxm = true;
         try {
-          const eventDb = new DatabaseSync(eventDbPath, { readOnly: true });
+          const eventDb = openReadOnlyDatabase(eventDbPath);
           try {
             eventDb.exec("PRAGMA busy_timeout = 5000");
             const runRows = eventDb.prepare(`

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.86";
+const VERSION = "0.7.88";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/memory.ts

@@ -245,10 +245,10 @@ export function createMemoryNote(
     body?: string | undefined;
     sourceRef?: string | undefined;
     runId?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { record: MemoryRecord; path: string } {
   const { candidatesDir } = memoryDirectories(repoRoot);
-  mkdirSync(candidatesDir, { recursive: true });
 
   const scope: MemoryScope = options.scope ?? "project";
   if (!VALID_SCOPES.has(scope)) {
@@ -277,6 +277,8 @@ export function createMemoryNote(
   };
 
   const targetPath = join(candidatesDir, `${id}.md`);
+  if (options.dryRun) return { record, path: targetPath };
+  mkdirSync(candidatesDir, { recursive: true });
   writeFileSync(targetPath, formatMemoryRecord(record), "utf8");
   return { record, path: targetPath };
 }
@@ -316,7 +318,8 @@ export function formatHarnessMemoryBlock(records: MemoryRecord[]): string {
   return contentLines.join("\n");
 }
 
-export function updateHarnessDocument(filePath: string, block: string, defaultHeader: string): boolean {
+/** Returns whether the projection block changed the file; `dryRun` answers without writing. */
+export function updateHarnessDocument(filePath: string, block: string, defaultHeader: string, dryRun = false): boolean {
   let original = "";
   if (existsSync(filePath)) {
     original = readFileSync(filePath, "utf8");
@@ -340,13 +343,13 @@ export function updateHarnessDocument(filePath: string, block: string, defaultHe
   }
 
   if (updated !== original) {
-    writeFileSync(filePath, updated, "utf8");
+    if (!dryRun) writeFileSync(filePath, updated, "utf8");
     return true;
   }
   return false;
 }
 
-export function syncHarnessMemory(repoRoot: string): { updated: string[]; created: string[] } {
+export function syncHarnessMemory(repoRoot: string, options: { dryRun?: boolean } = {}): { updated: string[]; created: string[] } {
   const root = resolve(repoRoot);
   const records = loadAuthoredMemory(root);
   const block = formatHarnessMemoryBlock(records);
@@ -358,7 +361,7 @@ export function syncHarnessMemory(repoRoot: string): { updated: string[]; create
   const agentsPath = join(root, "AGENTS.md");
   const agentsHeader = "# AGENTS\n\nFollow project instructions.\n";
   const agentsExisted = existsSync(agentsPath);
-  if (updateHarnessDocument(agentsPath, block, agentsHeader)) {
+  if (updateHarnessDocument(agentsPath, block, agentsHeader, options.dryRun)) {
     if (agentsExisted) updated.push("AGENTS.md");
     else created.push("AGENTS.md");
   }
@@ -367,7 +370,7 @@ export function syncHarnessMemory(repoRoot: string): { updated: string[]; create
   const claudePath = join(root, "CLAUDE.md");
   const claudeHeader = `# KXM (Claude)\n\nFollow [\`AGENTS.md\`](AGENTS.md). Official phase tracking:\n[\`plans/implementation-plan.md\`](plans/implementation-plan.md#tracking-working-tree-not-a-release).\n\nYou are the **planner / architecture critic** unless the human explicitly asks\nyou to implement. Default writer is native Grok CLI (\`grok --model grok-4.6\`) — a starting\nrotation, not a sole writer. If \`grok\` is logged out, never bill Grok through another harness;\nuse a relief route Tracking **admits**, or stop and name the limits hit. Your reviews are\nartifacts, not hub \`peer-reply\` evidence.\n`;
   const claudeExisted = existsSync(claudePath);
-  if (updateHarnessDocument(claudePath, block, claudeHeader)) {
+  if (updateHarnessDocument(claudePath, block, claudeHeader, options.dryRun)) {
     if (claudeExisted) updated.push("CLAUDE.md");
     else created.push("CLAUDE.md");
   }
@@ -376,7 +379,7 @@ export function syncHarnessMemory(repoRoot: string): { updated: string[]; create
   const geminiPath = join(root, "GEMINI.md");
   const geminiHeader = `# KXM (Gemini / Antigravity)\n\nFollow [\`AGENTS.md\`](AGENTS.md). Official phase tracking:\n[\`plans/implementation-plan.md\`](plans/implementation-plan.md#tracking-working-tree-not-a-release).\n\nGoogle goes through the \`antigravity\` **Pi provider** (Tracking \u2192 Decided,\n2026-09-15); \`agy\` stays a harness catalog/helper entry, not the admission path.\nCurrent admissions come from Tracking and \`kxm harness list\`. Starting rotation\nremains Grok.\n`;
   const geminiExisted = existsSync(geminiPath);
-  if (updateHarnessDocument(geminiPath, block, geminiHeader)) {
+  if (updateHarnessDocument(geminiPath, block, geminiHeader, options.dryRun)) {
     if (geminiExisted) updated.push("GEMINI.md");
     else created.push("GEMINI.md");
   }

package/plugins/kxm/src/role.ts

@@ -308,18 +308,21 @@ export function addRole(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     overwrite?: boolean | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = options.dryRun
+    ? rolesDirectory(scope, repoRoot, options.userConfigDir)
+    : ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${role.id}.yaml`);
 
   if (existsSync(filePath) && !options.overwrite) {
     throw new Error(`role_already_exists: role '${role.id}' already exists at ${filePath}`);
   }
 
-  writeFileSync(filePath, stringify(role), "utf8");
+  if (!options.dryRun) writeFileSync(filePath, stringify(role), "utf8");
   return { id: role.id, filePath, scope };
 }
 
@@ -329,6 +332,7 @@ export function removeRole(
     scope?: "global" | "local" | undefined;
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
@@ -340,6 +344,7 @@ export function removeRole(
     throw new Error(`role_not_found: role '${roleId}' not found in ${scope} directory (${filePath})`);
   }
 
+  if (options.dryRun) return { id: roleId, removed: false, filePath, scope };
   rmSync(filePath);
   return { id: roleId, removed: true, filePath, scope };
 }
@@ -351,6 +356,7 @@ export function modifyRole(
     scope?: "global" | "local" | undefined;
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; role: KxmRoleDefinition; filePath: string; scope: "global" | "local" } {
   const target = getRole(roleId, { scope: options.scope, repoRoot: options.repoRoot, userConfigDir: options.userConfigDir });
@@ -367,10 +373,12 @@ export function modifyRole(
 
   const scope = options.scope ?? target.scope;
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = options.dryRun
+    ? rolesDirectory(scope, repoRoot, options.userConfigDir)
+    : ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${roleId}.yaml`);
 
-  writeFileSync(filePath, stringify(updated), "utf8");
+  if (!options.dryRun) writeFileSync(filePath, stringify(updated), "utf8");
   return { id: roleId, role: updated, filePath, scope };
 }
 
@@ -562,17 +570,19 @@ export function saveRoleHostsConfig(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     format?: "yaml" | "json" | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
   const dir = scope === "global" ? userConfigDirectory(options.userConfigDir) : repoConfigDirectory(repoRoot);
+  const format = options.format ?? "yaml";
+  const filePath = join(dir, format === "json" ? "role-hosts.json" : "role-hosts.yaml");
+  if (options.dryRun) return { filePath, scope };
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
 
-  const format = options.format ?? "yaml";
-  const filePath = join(dir, format === "json" ? "role-hosts.json" : "role-hosts.yaml");
   const payload: RoleHostsConfig = {
     schema: KXM_ROLE_HOSTS_SCHEMA,
     seats: config.seats ?? {},
@@ -594,6 +604,7 @@ export function setRoleSeatHost(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     format?: "yaml" | "json" | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { filePath: string; seatId: string; binding: RoleSeatBinding; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
@@ -624,6 +635,7 @@ export function setRoleSeatHost(
     repoRoot: options.repoRoot,
     userConfigDir: options.userConfigDir,
     format: options.format,
+    dryRun: options.dryRun,
   });
 
   return { filePath: saved.filePath, seatId, binding, scope };

package/plugins/kxm/src/session-work.ts

@@ -398,6 +398,8 @@ export function loadSessionBrief(
     cost?: string;
     sessionToken?: string;
     ship?: SessionShipStatus;
+    /** false answers from disk and the hub without refreshing session-brief.json. */
+    writeCache?: boolean;
   } = {},
 ): SessionBrief {
   const paths = resolveKxmSnapshotPaths(cwd, env);
@@ -464,7 +466,7 @@ export function loadSessionBrief(
     );
   }
 
-  writeCachedSessionBrief(paths.stateDir, brief);
+  if (options.writeCache !== false) writeCachedSessionBrief(paths.stateDir, brief);
   return brief;
 }
 
@@ -479,6 +481,7 @@ export async function loadSessionBriefAsync(
     cost?: string;
     sessionToken?: string;
     ship?: SessionShipStatus;
+    writeCache?: boolean;
   } = {},
 ): Promise<SessionBrief> {
   const paths = resolveKxmSnapshotPaths(cwd, env);

package/plugins/kxm/src/skills.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { parse } from "yaml";
 import { redactSecrets } from "./redact.ts";
 
@@ -190,17 +190,32 @@ export interface SkillLifecycleOptions {
    * evals. When unset, `optimization` evaluations are rejected. */
   allowOptimizationEvals?: boolean;
   now?: () => string;
+  /** Validate and record every change in `planned` without touching disk. */
+  dryRun?: boolean;
 }
 
 export class SkillLifecycle {
   private readonly root: string;
   private readonly now: () => string;
   private readonly allowOptimizationEvals: boolean;
+  private readonly dryRun: boolean;
+  /** What a `dryRun` lifecycle would have written or moved, in order. */
+  readonly planned: Array<{ action: "write" | "move"; target: string }> = [];
 
   constructor(root: string, options: SkillLifecycleOptions = {}) {
     this.root = root;
     this.now = options.now ?? (() => new Date().toISOString());
     this.allowOptimizationEvals = options.allowOptimizationEvals === true;
+    this.dryRun = options.dryRun === true;
+  }
+
+  private write(file: string, content: string): void {
+    if (this.dryRun) {
+      this.planned.push({ action: "write", target: file });
+      return;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
   }
 
   private dir(state: SkillState): string {
@@ -217,15 +232,14 @@ export class SkillLifecycle {
   }
 
   private appendHistory(id: string, record: unknown): void {
-    mkdirSync(join(this.root, "history"), { recursive: true });
     const line = `${JSON.stringify(record)}\n`;
     if (existsSync(this.historyFile(id))) {
       // Bound the history file: append within the audit limit.
       const existing = readFileSync(this.historyFile(id), "utf8");
       const lines = existing.split("\n").filter((entry) => entry.trim());
-      writeFileSync(this.historyFile(id), [...lines.slice(-499), line.trim()].join("\n") + "\n");
+      this.write(this.historyFile(id), [...lines.slice(-499), line.trim()].join("\n") + "\n");
     } else {
-      writeFileSync(this.historyFile(id), line);
+      this.write(this.historyFile(id), line);
     }
   }
 
@@ -252,6 +266,10 @@ export class SkillLifecycle {
     if (!existsSync(fromDir)) {
       throw new SkillLifecycleError("skill_not_found", `skill ${id} not found in ${from}`);
     }
+    if (this.dryRun) {
+      this.planned.push({ action: "move", target: `${fromDir} -> ${toDir}` });
+      return;
+    }
     mkdirSync(this.dir(to), { recursive: true });
     if (existsSync(toDir)) rmSync(toDir, { recursive: true, force: true });
     renameSync(fromDir, toDir);
@@ -299,7 +317,7 @@ export class SkillLifecycle {
 
     const contentSha256 = skillContentSha256(content);
     const id = skillIdFor(name, contentSha256);
-    const { dir, metadata, skill } = this.paths("candidate", id);
+    const { metadata, skill } = this.paths("candidate", id);
     if (existsSync(metadata)) {
       throw new SkillLifecycleError(
         "skill_candidate_exists",
@@ -319,9 +337,8 @@ export class SkillLifecycle {
       createdAt: this.now(),
       ...(input.supersedes ? { supersedes: input.supersedes } : {}),
     };
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(skill, content);
-    writeFileSync(metadata, `${JSON.stringify(record, null, 2)}\n`);
+    this.write(skill, content);
+    this.write(metadata, `${JSON.stringify(record, null, 2)}\n`);
     this.appendHistory(id, { schema: "kxm.skill-history-event.v1", event: "candidate_created", by: createdBy, supersedes: input.supersedes, at: record.createdAt });
     return record;
   }
@@ -429,20 +446,17 @@ export class SkillLifecycle {
     // Instead of moving directory, write promoted directory and generate patch
     const candidatePaths = this.paths("candidate", candidateId);
     const promotedPaths = this.paths("promoted", candidateId);
-    mkdirSync(promotedPaths.dir, { recursive: true });
 
     const skillContent = readFileSync(candidatePaths.skill, "utf8");
     const metadataContent = readFileSync(candidatePaths.metadata, "utf8");
-    writeFileSync(promotedPaths.skill, skillContent);
-    writeFileSync(promotedPaths.metadata, metadataContent);
+    this.write(promotedPaths.skill, skillContent);
+    this.write(promotedPaths.metadata, metadataContent);
 
-    const patchesDir = join(this.root, "patches");
-    mkdirSync(patchesDir, { recursive: true });
-    const patchPath = join(patchesDir, `${candidateId}.patch`);
+    const patchPath = join(this.root, "patches", `${candidateId}.patch`);
     const relSkillPath = `.kxm/skills/promoted/${candidateId}/SKILL.md`;
     const relMetaPath = `.kxm/skills/promoted/${candidateId}/metadata.json`;
     const patch = `${createUnifiedPatch(relSkillPath, skillContent)}${createUnifiedPatch(relMetaPath, metadataContent)}`;
-    writeFileSync(patchPath, patch, "utf8");
+    this.write(patchPath, patch);
 
     this.appendHistory(candidateId, record);
     return { ...metadata, patch, patchPath };

package/plugins/kxm/src/sqlite.ts

@@ -8,7 +8,10 @@
  * flag `readOnly`, Bun spells it `readonly`. Options are normalized here so
  * callers keep using the Node spelling everywhere.
  */
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 
 export interface DatabaseSyncOptions {
   readOnly?: boolean;
@@ -74,3 +77,18 @@ export class DatabaseSync {
     this.inner.close();
   }
 }
+
+/**
+ * Open a database for reading without touching its directory. A plain
+ * read-only open of a WAL database creates the `-wal` and `-shm` sidecars when
+ * they are missing and leaves them behind. With no `-wal` present, the main
+ * file already holds every committed page, so it is opened `immutable` (no
+ * locks, no sidecars); a present `-wal` means a writer or un-checkpointed
+ * frames, and the ordinary read-only open reads through them.
+ */
+export function openReadOnlyDatabase(path: string): DatabaseSync {
+  if (existsSync(`${path}-wal`)) return new DatabaseSync(path, { readOnly: true });
+  const uri = pathToFileURL(resolve(path));
+  uri.searchParams.set("immutable", "1");
+  return new DatabaseSync(uri.href, { readOnly: true });
+}