@klhapp/skillmux 1.9.3 → 1.10.0

package/src/commands/sync.ts

@@ -0,0 +1,232 @@
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import { expandHome, loadConfig } from "../config";
+import {
+  parseManifest,
+  resolveManifestPath,
+  validateManifest,
+} from "../manifest";
+import { emitSuccess, isInteractive, warn } from "../output";
+import {
+  installPostMergeHook,
+  resolveProjectPinDir,
+  restoreMonolith as restoreMonolithTarget,
+  syncProjectTargets,
+  syncTarget,
+  type ProjectGroupInput,
+} from "../sync";
+import { confirmAction } from "./shared";
+
+function parseSyncArgs(args: string[]): {
+  dryRun: boolean;
+  restoreMonolith: boolean;
+  installHook: boolean;
+  yes: boolean;
+  isJson: boolean;
+} {
+  let dryRun = false;
+  let restoreMonolith = false;
+  let installHook = false;
+  let yes = false;
+  let isJson = false;
+  for (const arg of args) {
+    if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--restore-monolith") restoreMonolith = true;
+    else if (arg === "--install-hook") installHook = true;
+    else if (arg === "--yes") yes = true;
+    else if (arg === "--json") isJson = true;
+    else throw new Error(`unknown sync option: ${arg}`);
+  }
+  return { dryRun, restoreMonolith, installHook, yes, isJson };
+}
+
+/**
+ * A target directory that doesn't exist yet is about to be created by `sync`.
+ * `manifest.targets[*].dir` is vault content — readable and writable by whatever
+ * populated the vault (a shared git-backed vault pulled in, or a hand-edit) — and
+ * `sync` can run unattended via the `--install-hook` post-merge hook. Without this
+ * gate, a tampered manifest naming a brand-new path gets that directory silently
+ * created (and populated with symlinks) the next time anyone pulls. Creation for
+ * an as-yet-unseen directory therefore requires either `--yes` or an interactive
+ * confirmation; once the directory exists, later syncs never hit this path again.
+ */
+async function confirmNewSyncTarget(
+  label: string,
+  dir: string,
+  yes: boolean,
+  isJson: boolean,
+): Promise<boolean> {
+  if (yes) return true;
+  if (!isInteractive()) {
+    if (!isJson) {
+      console.log(
+        `${label}: skipped — ${dir} does not exist yet; creating it requires approval. Re-run "skillmux sync --yes", or run "skillmux sync" interactively, once you've confirmed this target is expected.`,
+      );
+    }
+    return false;
+  }
+  return confirmAction(`${label}: create new target directory ${dir}?`);
+}
+
+interface SyncTargetSummary {
+  target: string;
+  status:
+    | "synced"
+    | "skipped_host_mismatch"
+    | "restored"
+    | "not_owned"
+    | "skipped_not_approved";
+  added?: string[];
+  removed?: string[];
+  skipped?: string[];
+  projects?: {
+    group: string;
+    pin_dir: string;
+    added: string[];
+    removed: string[];
+    skipped: string[];
+  }[];
+}
+
+export async function runSync(args: string[]): Promise<void> {
+  const { dryRun, restoreMonolith, installHook, yes, isJson } = parseSyncArgs(args);
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const log = (line: string) => {
+    if (!isJson) console.log(line);
+  };
+  const warnLine = (line: string) => {
+    if (!isJson) warn(line);
+  };
+
+  let hookInstalled: boolean | undefined;
+  if (installHook) {
+    const result = installPostMergeHook(vaultPath);
+    hookInstalled = result.installed;
+    log(result.installed ? "installed post-merge hook" : "post-merge hook already installed");
+  }
+
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) {
+    emitSuccess({ isJson }, { hook_installed: hookInstalled ?? null, targets: [] }, () =>
+      console.log("no skillmux.toml found at vault root — nothing to sync"),
+    );
+    return;
+  }
+
+  const manifest = parseManifest(await Bun.file(manifestPath).text());
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const { notes } = validateManifest(manifest, vaultPath, localVaultPaths);
+  for (const note of notes) log(`note: ${note}`);
+
+  const currentHost = hostname();
+  const targetSummaries: SyncTargetSummary[] = [];
+  for (const [targetName, target] of Object.entries(manifest.targets)) {
+    if (target.host !== undefined && target.host !== currentHost) {
+      log(
+        `${targetName}: skipped (host ${target.host} does not match current host ${currentHost})`,
+      );
+      targetSummaries.push({ target: targetName, status: "skipped_host_mismatch" });
+      continue;
+    }
+    const targetDir = expandHome(target.dir);
+
+    if (restoreMonolith) {
+      const result = restoreMonolithTarget(targetDir, vaultPath);
+      log(
+        result.restored
+          ? `${targetName}: restored to a vault symlink`
+          : `${targetName}: not owned by skillmux, left untouched`,
+      );
+      targetSummaries.push({
+        target: targetName,
+        status: result.restored ? "restored" : "not_owned",
+      });
+      continue;
+    }
+
+    if (!dryRun && !existsSync(targetDir)) {
+      const approved = await confirmNewSyncTarget(targetName, targetDir, yes, isJson);
+      if (!approved) {
+        if (isInteractive()) {
+          log(`${targetName}: skipped — creating ${targetDir} was not approved`);
+        }
+        targetSummaries.push({ target: targetName, status: "skipped_not_approved" });
+        continue;
+      }
+    }
+
+    const suffix = dryRun ? " (dry-run)" : "";
+    const result = syncTarget(
+      {
+        vaultPath,
+        targetDir,
+        targetName,
+        coreSkillIds: manifest.core.skills,
+        localVaultPaths,
+      },
+      { dryRun },
+    );
+    log(`${targetName}: +${result.added.length} -${result.removed.length}${suffix}`);
+    if (result.skipped.length > 0) {
+      warnLine(`refused to sync ${result.skipped.join(", ")} — skill directory contains a symlink`);
+    }
+    const summary: SyncTargetSummary = {
+      target: targetName,
+      status: "synced",
+      added: result.added,
+      removed: result.removed,
+      skipped: result.skipped,
+    };
+
+    if (target.project_groups.length > 0) {
+      const allGroups = manifest.project ?? {};
+      const projectGroups: Record<string, ProjectGroupInput> = {};
+      for (const groupName of target.project_groups) {
+        const group = allGroups[groupName]!;
+        const approvedPaths: string[] = [];
+        for (const path of group.paths) {
+          // Mirror syncProjectTargets' own `if (!existsSync(path)) continue` so we
+          // never prompt for a project path it would silently skip anyway.
+          if (!existsSync(path)) continue;
+          const pinDir = resolveProjectPinDir(targetDir, path);
+          if (dryRun || existsSync(pinDir)) {
+            approvedPaths.push(path);
+            continue;
+          }
+          const approved = await confirmNewSyncTarget(`${targetName}/${groupName}`, pinDir, yes, isJson);
+          if (approved) approvedPaths.push(path);
+        }
+        projectGroups[groupName] = { ...group, paths: approvedPaths };
+      }
+      const projectResults = syncProjectTargets(
+        { vaultPath, targetDir, targetName, projectGroups, localVaultPaths },
+        { dryRun },
+      );
+      summary.projects = projectResults.map((projectResult) => ({
+        group: projectResult.group,
+        pin_dir: projectResult.pinDir,
+        added: projectResult.added,
+        removed: projectResult.removed,
+        skipped: projectResult.skipped,
+      }));
+      for (const projectResult of projectResults) {
+        log(
+          `  ${projectResult.group} -> ${projectResult.pinDir}: +${projectResult.added.length} -${projectResult.removed.length}${suffix}`,
+        );
+        if (projectResult.skipped.length > 0) {
+          warnLine(
+            `refused to sync ${projectResult.skipped.join(", ")} — skill directory contains a symlink`,
+          );
+        }
+      }
+    }
+    targetSummaries.push(summary);
+  }
+
+  emitSuccess(
+    { isJson },
+    { hook_installed: hookInstalled ?? null, notes, targets: targetSummaries },
+    () => {},
+  );
+}

package/src/commands/target.ts

@@ -63,14 +63,16 @@ export async function runTarget(
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `Adopt target ${name} at ${path}?`,
+        prompt: `adopt target ${name} at ${path}?`,
         nonInteractiveError:
           "skillmux target add requires --yes when run non-interactively",
       }))
     )
       return;
     applyInit(vaultPath, [{ name, dir: path }]);
-    console.log(`target "${name}" added at ${path}`);
+    emitSuccess({ isJson: options.isJson }, { name, dir: path }, () =>
+      console.log(`target "${name}" added at ${path}`),
+    );
     return;
   }
 
@@ -84,24 +86,34 @@ export async function runTarget(
       );
     }
     if (options.dryRun) {
-      console.log(`target remove: ${name} (files preserved, dry-run)`);
+      emitSuccess(
+        { isJson: options.isJson },
+        { name, preserved_dir: manifest.targets[name]!.dir },
+        () => console.log(`target remove: ${name} (files preserved, dry-run)`),
+      );
       return;
     }
     if (
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `Remove target ${name} from the manifest and preserve its files?`,
+        prompt: `remove target ${name} from the manifest and preserve its files?`,
         nonInteractiveError:
           "skillmux target remove requires --yes when run non-interactively",
       }))
     )
       return;
     const targets = { ...manifest.targets };
+    const removedDir = manifest.targets[name]!.dir;
     delete targets[name];
     writeManifestAtomic(manifestPath, { ...manifest, targets });
-    console.log(
-      `target "${name}" removed from the manifest; files preserved at ${manifest.targets[name]!.dir}`,
+    emitSuccess(
+      { isJson: options.isJson },
+      { name, preserved_dir: removedDir },
+      () =>
+        console.log(
+          `target "${name}" removed from the manifest; files preserved at ${removedDir}`,
+        ),
     );
     return;
   }

package/src/commands/update.ts

@@ -18,6 +18,7 @@ import { type ScanFinding, type ScanSeverity, scanExitCode } from "../scan";
 import { SKILL_ID_PATTERN } from "../vault";
 import { confirmIfNeeded } from "./shared";
 import { checkOutdated } from "./outdated";
+import { isGlobalFlag } from "../global-flags";
 
 type UpdateKind = "update" | "up_to_date" | "skip_drift" | "skip_scan_failed" | "skip_read_error";
 
@@ -195,7 +196,7 @@ function parseUpdateArgs(args: string[]): {
         throw new Error("--fail-on must be low, medium, or high");
       }
       failOn = value;
-    } else if (arg === "--json") {
+    } else if (isGlobalFlag(arg, "--json")) {
       // handled globally
     } else if (arg?.startsWith("--")) {
       throw new Error(`unknown update option: ${arg}`);

package/src/config-service.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { DEFAULT_CONFIG_PATH, expandHome, loadConfig } from "./config";
 import { describeDeployment } from "./deployment";
 import type { Config } from "./types";
+import { stringifyToml } from "./toml-writer";
 
 export type ConfigSource = "default" | "toml" | "environment";
 export type ConfigSourceMap = Record<string, ConfigSource>;
@@ -373,57 +374,6 @@ export async function setDottedKey(
   };
 }
 
-export function stringifyToml(obj: Record<string, any>): string {
-  let out = "";
-  const topLevel: Record<string, any> = {};
-  const sections: Record<string, any> = {};
-
-  for (const [k, v] of Object.entries(obj)) {
-    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
-      sections[k] = v;
-    } else {
-      topLevel[k] = v;
-    }
-  }
-
-  for (const [k, v] of Object.entries(topLevel)) {
-    out += `${k} = ${formatTomlVal(v)}\n`;
-  }
-  if (Object.keys(topLevel).length > 0) out += "\n";
-
-  for (const [secName, secObj] of Object.entries(sections)) {
-    out += stringifyTomlSection([secName], secObj);
-  }
-
-  return out;
-}
-
-function stringifyTomlSection(path: string[], obj: Record<string, any>): string {
-  let out = `[${path.join(".")}]\n`;
-  const subSections: Record<string, any> = {};
-
-  for (const [k, v] of Object.entries(obj)) {
-    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
-      subSections[k] = v;
-    } else {
-      out += `${k} = ${formatTomlVal(v)}\n`;
-    }
-  }
-  out += "\n";
-
-  for (const [subName, subObj] of Object.entries(subSections)) {
-    out += stringifyTomlSection([...path, subName], subObj);
-  }
-
-  return out;
-}
-
-function formatTomlVal(v: unknown): string {
-  if (typeof v === "string") return JSON.stringify(v);
-  if (typeof v === "boolean" || typeof v === "number") return String(v);
-  if (Array.isArray(v)) return JSON.stringify(v);
-  return JSON.stringify(v);
-}
 
 export async function getLocalConfigStatus(configPath?: string): Promise<ConfigStatusResponse> {
   const { effective } = await getEffectiveConfig(configPath);

package/src/context.ts

@@ -12,7 +12,12 @@ export interface ContextConfig {
   contexts: Record<string, ContextRecord>;
 }
 
-export type ResolvedTarget =
+/**
+ * Context resolution: `local` = this CLI process has the Skillmux runtime (vault,
+ * index, audit db, embeddings/reranker clients) loaded in-process; `remote` = this
+ * CLI process is a thin network client to a separate process elsewhere that owns that runtime.
+ */
+export type ResolvedContext =
   | { type: "local"; name: "local" }
   | { type: "remote"; name: string; server: string; token_env?: string };
 
@@ -127,10 +132,10 @@ export async function useContext(name: string, filePath?: string): Promise<void>
   await saveContextConfig(config, filePath);
 }
 
-export async function resolveTarget(
+export async function resolveContext(
   flags: { context?: string; server?: string },
   filePath?: string
-): Promise<ResolvedTarget> {
+): Promise<ResolvedContext> {
   // Precedence 1: Explicit flags
   if (flags.context && flags.server) {
     throw new Error("Cannot specify both --context and --server");

package/src/db-audit.ts

@@ -0,0 +1,286 @@
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { AuditCandidate, AuditRow } from "./types";
+
+export function openAudit(stateDir: string): Database {
+  mkdirSync(stateDir, { recursive: true });
+  const db = new Database(join(stateDir, "audit.sqlite3"), { create: true });
+  // auto_vacuum only takes on an empty database, so it must precede both the
+  // journal-mode switch and any CREATE TABLE. It is what lets a retention
+  // prune reclaim space without a full VACUUM.
+  db.run("PRAGMA auto_vacuum = INCREMENTAL");
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA busy_timeout = 2000");
+  db.run(`CREATE TABLE IF NOT EXISTS audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    request_id TEXT,
+    query TEXT NOT NULL,
+    retrieval TEXT NOT NULL DEFAULT 'lexical',
+    degraded_from TEXT,
+    degradation_reason TEXT,
+    candidates TEXT NOT NULL,
+    latency_ms INTEGER NOT NULL
+  )`);
+  // CREATE TABLE IF NOT EXISTS no-ops on a table opened from before request_id
+  // existed (AC4), so add it explicitly when missing.
+  const auditColumns = new Set(
+    (db.query("PRAGMA table_info(audit)").all() as { name: string }[]).map((c) => c.name),
+  );
+  if (!auditColumns.has("request_id")) {
+    db.run("ALTER TABLE audit ADD COLUMN request_id TEXT");
+  }
+  db.run(`CREATE TABLE IF NOT EXISTS fetch (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    skill_id TEXT NOT NULL,
+    request_id TEXT,
+    resolve_audit_id INTEGER,
+    rank_at_resolve INTEGER
+  )`);
+  db.run(`CREATE TABLE IF NOT EXISTS admin_audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    changes TEXT NOT NULL,
+    resulting_revision TEXT NOT NULL,
+    row_hash TEXT NOT NULL,
+    prev_row_hash TEXT
+  )`);
+  adoptAuditFromIndex(db, stateDir);
+  return db;
+}
+
+// Audit rows used to live in index.sqlite3. Move any that remain there into the
+// audit store, then drop the old table so the index carries no user queries.
+function adoptAuditFromIndex(db: Database, stateDir: string): void {
+  const indexPath = join(stateDir, "index.sqlite3");
+  if (!existsSync(indexPath)) return;
+
+  db.run("ATTACH DATABASE ? AS legacy", [indexPath]);
+  try {
+    const legacyAudit = db
+      .query("SELECT name FROM legacy.sqlite_master WHERE type = 'table' AND name = 'audit'")
+      .get();
+    if (!legacyAudit) return;
+
+    // Older audit tables predate the retrieval columns and carry outcome /
+    // degraded / selected_skill_id instead. Select what is actually there and
+    // let the canonical defaults stand in for the rest.
+    const legacyColumns = new Set(
+      (db.query("PRAGMA legacy.table_info(audit)").all() as { name: string }[]).map((c) => c.name),
+    );
+    const retrieval = legacyColumns.has("retrieval") ? "COALESCE(retrieval, 'lexical')" : "'lexical'";
+    const degradedFrom = legacyColumns.has("degraded_from") ? "degraded_from" : "NULL";
+    const degradationReason = legacyColumns.has("degradation_reason") ? "degradation_reason" : "NULL";
+
+    // SQLite commits atomically across attached databases, so the copy and the
+    // drop either both land or neither does.
+    db.transaction(() => {
+      db.run(`INSERT INTO audit (ts, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms)
+        SELECT ts, query, ${retrieval}, ${degradedFrom}, ${degradationReason}, candidates, latency_ms FROM legacy.audit`);
+      db.run("DROP TABLE legacy.audit");
+    })();
+  } finally {
+    db.run("DETACH DATABASE legacy");
+  }
+}
+
+export interface AuditInsert {
+  ts: string;
+  request_id?: string | null;
+  query: string;
+  retrieval: AuditRow["retrieval"];
+  degraded_from?: string | null;
+  degradation_reason?: string | null;
+  candidates: AuditCandidate[];
+  latency_ms: number;
+}
+
+export function insertAudit(db: Database, row: AuditInsert): void {
+  db.run(
+    `INSERT INTO audit (ts, request_id, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      row.ts,
+      row.request_id ?? null,
+      row.query,
+      row.retrieval,
+      row.degraded_from ?? null,
+      row.degradation_reason ?? null,
+      JSON.stringify(row.candidates),
+      row.latency_ms,
+    ],
+  );
+}
+
+/**
+ * Correlation lookup for AC5/AC7: looks up the resolve that produced
+ * `requestId`, or null when it names no known resolve (including malformed
+ * input, which is never validated at the boundary per AC7).
+ */
+export function getAuditRowByRequestId(
+  db: Database,
+  requestId: string,
+): { id: number; candidates: AuditCandidate[] } | null {
+  const row = db
+    .query("SELECT id, candidates FROM audit WHERE request_id = ?")
+    .get(requestId) as { id: number; candidates: string } | null;
+  if (!row) return null;
+  return { id: row.id, candidates: JSON.parse(row.candidates) as AuditCandidate[] };
+}
+
+export interface FetchInsert {
+  ts: string;
+  skill_id: string;
+  request_id?: string | null;
+  resolve_audit_id?: number | null;
+  rank_at_resolve?: number | null;
+}
+
+export function insertFetch(db: Database, row: FetchInsert): void {
+  db.run(
+    `INSERT INTO fetch (ts, skill_id, request_id, resolve_audit_id, rank_at_resolve)
+     VALUES (?, ?, ?, ?, ?)`,
+    [
+      row.ts,
+      row.skill_id,
+      row.request_id ?? null,
+      row.resolve_audit_id ?? null,
+      row.rank_at_resolve ?? null,
+    ],
+  );
+}
+
+export interface PruneResult {
+  audit_deleted: number;
+  fetch_deleted: number;
+  admin_audit_deleted: number;
+}
+
+/**
+ * Deletes resolve, fetch, and admin_audit rows with ts before `cutoffIso`,
+ * each by its own timestamp; no FK ties them, so a fetch outliving its
+ * resolve row simply reads back uncorrelated (AC7's existing null path).
+ * admin_audit shares this cutoff rather than a separate retention config
+ * (AC10) — its hash chain is unaffected since pruning only ever removes the
+ * oldest rows, never rows in the middle of the chain. Reclaims the freed
+ * pages with an incremental vacuum, which only touches audit.sqlite3 (AC16).
+ */
+export function pruneAuditBefore(db: Database, cutoffIso: string): PruneResult {
+  const auditResult = db.run("DELETE FROM audit WHERE ts < ?", [cutoffIso]);
+  const fetchResult = db.run("DELETE FROM fetch WHERE ts < ?", [cutoffIso]);
+  const adminAuditResult = db.run("DELETE FROM admin_audit WHERE ts < ?", [cutoffIso]);
+  db.run("PRAGMA incremental_vacuum");
+
+  return {
+    audit_deleted: auditResult.changes,
+    fetch_deleted: fetchResult.changes,
+    admin_audit_deleted: adminAuditResult.changes,
+  };
+}
+
+/** AC12: retentionDays <= 0 disables pruning entirely. */
+export function pruneAudit(db: Database, retentionDays: number, now: Date = new Date()): PruneResult {
+  if (retentionDays <= 0) return { audit_deleted: 0, fetch_deleted: 0, admin_audit_deleted: 0 };
+  const cutoff = new Date(now.getTime() - retentionDays * 86_400_000).toISOString();
+  return pruneAuditBefore(db, cutoff);
+}
+
+export interface AdminAuditChange {
+  key: string;
+  old_value: unknown;
+  new_value: unknown;
+}
+
+export interface AdminAuditInsert {
+  ts: string;
+  changes: AdminAuditChange[];
+  resulting_revision: string;
+}
+
+export interface AdminAuditRow {
+  id: number;
+  ts: string;
+  changes: AdminAuditChange[];
+  resulting_revision: string;
+  row_hash: string;
+  prev_row_hash: string | null;
+}
+
+function computeAdminAuditRowHash(
+  prevRowHash: string | null,
+  fields: { ts: string; changes: AdminAuditChange[]; resulting_revision: string },
+): string {
+  const payload = JSON.stringify({ prev_row_hash: prevRowHash, ...fields });
+  return createHash("sha256").update(payload).digest("hex");
+}
+
+/**
+ * Appends one tamper-evident admin_audit row, chaining its hash to the
+ * previous row's hash (or null for the first row) so any out-of-band
+ * edit/delete breaks the chain — see verifyAdminAuditChain.
+ */
+export function insertAdminAuditRow(db: Database, row: AdminAuditInsert): AdminAuditRow {
+  const prevRow = db
+    .query("SELECT row_hash FROM admin_audit ORDER BY id DESC LIMIT 1")
+    .get() as { row_hash: string } | null;
+  const prevRowHash = prevRow?.row_hash ?? null;
+  const rowHash = computeAdminAuditRowHash(prevRowHash, row);
+
+  db.run(
+    `INSERT INTO admin_audit (ts, changes, resulting_revision, row_hash, prev_row_hash)
+     VALUES (?, ?, ?, ?, ?)`,
+    [row.ts, JSON.stringify(row.changes), row.resulting_revision, rowHash, prevRowHash],
+  );
+
+  const inserted = db.query("SELECT last_insert_rowid() AS id").get() as { id: number };
+  return {
+    id: inserted.id,
+    ts: row.ts,
+    changes: row.changes,
+    resulting_revision: row.resulting_revision,
+    row_hash: rowHash,
+    prev_row_hash: prevRowHash,
+  };
+}
+
+export interface AdminAuditChainResult {
+  valid: boolean;
+  broken_at_id: number | null;
+}
+
+/** Walks admin_audit in insertion order and reports whether the hash chain is unbroken. */
+export function verifyAdminAuditChain(db: Database): AdminAuditChainResult {
+  const rows = db
+    .query("SELECT id, ts, changes, resulting_revision, row_hash, prev_row_hash FROM admin_audit ORDER BY id ASC")
+    .all() as { id: number; ts: string; changes: string; resulting_revision: string; row_hash: string; prev_row_hash: string | null }[];
+
+  let expectedPrevHash: string | null = null;
+  for (const row of rows) {
+    if (row.prev_row_hash !== expectedPrevHash) {
+      return { valid: false, broken_at_id: row.id };
+    }
+    const recomputed = computeAdminAuditRowHash(expectedPrevHash, {
+      ts: row.ts,
+      changes: JSON.parse(row.changes),
+      resulting_revision: row.resulting_revision,
+    });
+    if (recomputed !== row.row_hash) {
+      return { valid: false, broken_at_id: row.id };
+    }
+    expectedPrevHash = row.row_hash;
+  }
+  return { valid: true, broken_at_id: null };
+}
+
+/** Dry-run counterpart of pruneAuditBefore: counts without deleting (AC15). */
+export function countPrunable(db: Database, cutoffIso: string): PruneResult {
+  const auditRow = db.query("SELECT count(*) AS n FROM audit WHERE ts < ?").get(cutoffIso) as { n: number };
+  const fetchRow = db.query("SELECT count(*) AS n FROM fetch WHERE ts < ?").get(cutoffIso) as { n: number };
+  const adminAuditRow = db
+    .query("SELECT count(*) AS n FROM admin_audit WHERE ts < ?")
+    .get(cutoffIso) as { n: number };
+  return { audit_deleted: auditRow.n, fetch_deleted: fetchRow.n, admin_audit_deleted: adminAuditRow.n };
+}