@klhapp/skillmux 1.9.3 → 1.11.0

package/src/completions.ts

@@ -1,3 +1,5 @@
+import { MANAGED_PINS_AGENT_IDS, SUPPORTED_AGENT_IDS } from "./init-agents";
+
 export type ShellType = "bash" | "zsh" | "fish";
 
 const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
@@ -6,7 +8,7 @@ const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
   { name: "serve", description: "Start MCP server" },
   { name: "index", description: "Rebuild local search index" },
   { name: "sync", description: "Synchronize vault skills" },
-  { name: "init", description: "Configure this machine and its clients" },
+  { name: "init", description: "Configure this machine and its agents" },
   { name: "project", description: "Configure project-scoped skills" },
   { name: "target", description: "Manage advanced skill-delivery targets" },
   { name: "core", description: "Pin/unpin skills into [core]" },
@@ -62,18 +64,25 @@ _skillmux_completions() {
         local-vault)
             COMPREPLY=( $(compgen -W "init" -- "$cur") )
             ;;
-        --client)
-            COMPREPLY=( $(compgen -W "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -- "$cur") )
+        eval)
+            COMPREPLY=( $(compgen -W "promote" -- "$cur") )
             ;;
-        --target)
-            COMPREPLY=( $(compgen -W "agent-skills claude-code codex custom" -- "$cur") )
+        --agent)
+            if [ "\${COMP_WORDS[1]}" = "project" ]; then
+                COMPREPLY=( $(compgen -W "${MANAGED_PINS_AGENT_IDS.join(" ")}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${SUPPORTED_AGENT_IDS.join(" ")}" -- "$cur") )
+            fi
             ;;
     esac
     if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
-        COMPREPLY=( $(compgen -W "--client --target --dir --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--agent --vault --core --migrate-full-vault --show-mcp-setup --register-mcp --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
     fi
     if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
-        COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--name --skill --agent --target --register-mcp --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
+    if [ "\${COMP_WORDS[1]}" = "eval" ] && [ "\${COMP_WORDS[2]}" = "promote" ]; then
+        COMPREPLY=( $(compgen -W "--since --out --dry-run --yes --json" -- "$cur") )
     fi
 }
 complete -F _skillmux_completions skillmux
@@ -92,12 +101,12 @@ ${commands}
         _describe -t commands 'skillmux command' commands
     elif [[ "$words[2]" == "init" ]]; then
         _arguments \\
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \\
-          '*--target[select a delivery target]:target:(agent-skills claude-code codex custom)' \\
-          '--dir[custom target directory]:directory:_directories' \\
+          '*--agent[select an agent]:agent:(${SUPPORTED_AGENT_IDS.join(" ")})' \\
           '--vault[vault directory]:directory:_directories' \\
           '*--core[seed a core skill]:skill id:' \\
           '--migrate-full-vault[convert a full-vault symlink to managed pins]' \\
+          '--show-mcp-setup[also print the MCP registration snippet]' \\
+          '--register-mcp[register skillmux via the agent own CLI]' \\
           '--no-instructions[skip managed instruction files]' \\
           '--no-sync[save setup without synchronizing targets]' \\
           '--interactive[force guided setup]' \\
@@ -109,8 +118,9 @@ ${commands}
           '1:project directory:_directories' \\
           '--name[project group name]:group:' \\
           '*--skill[project skill]:skill id:' \\
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \\
+          '*--agent[select an agent]:agent:(${MANAGED_PINS_AGENT_IDS.join(" ")})' \\
           '*--target[select an advanced target]:target:' \\
+          '--register-mcp[register a project-scoped MCP server for claude-code]' \\
           '--no-sync[save setup without synchronizing targets]' \\
           '--interactive[force guided setup]' \\
           '--yes[apply without prompts]' \\
@@ -118,6 +128,15 @@ ${commands}
           '--json[emit a JSON envelope]'
     elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
         _values 'project command' init list show add-path remove-path pin unpin attach detach
+    elif [[ "$words[2]" == "eval" && "$words[3]" == "promote" ]]; then
+        _arguments \
+          '--since[time window]:window:' \
+          '--out[output file]:file:_files' \
+          '--dry-run[print the plan without writing]' \
+          '--yes[apply without prompts]' \
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "eval" && CURRENT == 3 ]]; then
+        _values 'eval command' promote
     elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
         _values 'target command' list show add remove
     elif [[ "$words[2]" == "skill" && CURRENT == 3 ]]; then
@@ -139,12 +158,12 @@ _skillmux "$@"
     return `# fish completion for skillmux
 complete -c skillmux -f
 ${topLevel}
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a delivery target"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l dir -r -d "Custom target directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l agent -x -a "${SUPPORTED_AGENT_IDS.join(" ")}" -d "Select an agent"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l show-mcp-setup -d "Also print the MCP registration snippet"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l register-mcp -d "Register skillmux via the agent's own CLI"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-instructions -d "Skip managed instruction files"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l interactive -d "Force guided setup"
@@ -154,11 +173,18 @@ complete -c skillmux -n "__fish_seen_subcommand_from init" -l json -d "Emit a JS
 complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show add-path remove-path pin unpin attach detach" -d "Manage projects"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
-complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l agent -x -a "${MANAGED_PINS_AGENT_IDS.join(" ")}" -d "Select an agent"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced delivery target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l register-mcp -d "Register a project-scoped MCP server for claude-code"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from eval" -a "promote" -d "Promote correlated fetches into eval cases"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l since -x -d "Time window"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l out -r -d "Output file"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l dry-run -d "Print the plan without writing"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l json -d "Emit a JSON envelope"
 complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
 complete -c skillmux -n "__fish_seen_subcommand_from core" -a "pin unpin" -d "Manage [core] pins"
 complete -c skillmux -n "__fish_seen_subcommand_from skill" -a "which" -d "Show which root resolves a skill_id"

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>;
@@ -308,7 +309,7 @@ export async function getDottedKey(key: string, configPath?: string): Promise<un
 export async function setDottedKey(
   key: string,
   rawValStr: string,
-  opts?: { configPath?: string; dryRun?: boolean; targetName?: string }
+  opts?: { configPath?: string; dryRun?: boolean; contextName?: string }
 ): Promise<SetConfigResult> {
   validateDottedKey(key);
   if (isEnvMasked(key)) {
@@ -316,7 +317,7 @@ export async function setDottedKey(
   }
 
   const path = opts?.configPath ?? process.env.SKILLMUX_CONFIG ?? DEFAULT_CONFIG_PATH;
-  const targetName = opts?.targetName ?? "local";
+  const contextName = opts?.contextName ?? "local";
 
   const { effective: priorEffective, rawToml } = await getEffectiveConfig(path);
   const priorVal = getNestedValue(priorEffective as Record<string, any>, key);
@@ -363,7 +364,7 @@ export async function setDottedKey(
     key,
     prior_val: priorVal,
     resulting_val: parsedVal,
-    target: targetName,
+    target: contextName,
     prior_revision: priorRevision,
     resulting_revision: resultingRevision,
     persistence,
@@ -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 };
+}