ruvnet-brain 3.9.134-dev → 4.0.2

package/scripts/count-chunks.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// scripts/count-chunks.mjs — recount the REAL passage total across the local PUBLIC kb stores and
+// restamp it onto every public surface that advertises it. Rule: no number beats a wrong number —
+// the hand-typed "129,685 source chunks" rotted (SOURCE.json advertised a corpus that had moved on)
+// and was pulled from every surface in v3.2.5. This script is how it comes back honestly: computed
+// fresh from disk every time, never hand-typed again.
+//
+// NOTHING is duplicated here — neither the counting nor the restamping. Both live in
+// claims-verify.mjs (`applyFix`), the same module whose `verifyChunkCountSurfaces` gates the result,
+// and this file is a thin CLI over it. That is deliberate: a second writer with its own regexes is
+// how four surfaces drift four ways in the first place. Private stores (kb/PRIVATE-STORES.json) are
+// fenced out by the shared counter, so the public number can never include private content.
+//
+// A surface with NO existing "N chunks" claim (e.g. explainer/index.html before this was restored)
+// is reported, not silently improvised into someone else's prose — the first stamp on a new surface
+// is a deliberate one-time copy edit, done by hand once; after that this script keeps it fresh.
+//
+// Usage:  node scripts/count-chunks.mjs            # recount + write the fresh census into every surface
+//         node scripts/count-chunks.mjs --check     # report only; exit 1 if any surface would change
+//
+// `npm run claims:fix` does this AND the coverage badge in one pass; prefer it. This entry point
+// stays because the nightly brain rebuild wants the census restamped without touching coverage.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyFix } from './claims-verify.mjs';
+
+const CHECK = process.argv.includes('--check');
+
+async function main() {
+  // summaryFile deliberately points nowhere: this entry point restamps the CENSUS only, and the
+  // coverage half then reports itself as "not stamped" rather than silently doing half a job.
+  const report = await applyFix({ write: !CHECK, summaryFile: path.join('/nonexistent', 'coverage-summary.json') });
+  if (!report.census) {
+    console.error('[count-chunks] no public kb stores found under kb/*.big.rvf.idmap.json — is the local brain built? Nothing to stamp.');
+    process.exit(1);
+  }
+  const { chunks, publicStores, builtStores } = report.census;
+  const want = chunks.toLocaleString('en-US');
+  console.log(`[count-chunks] recounted ${want} chunks across ${publicStores} public stores of ${builtStores} built (private stores excluded per kb/PRIVATE-STORES.json)`);
+  for (const n of report.notes) console.warn(`[count-chunks] ${n}`);
+
+  const drifted = report.changed;
+  if (CHECK && drifted.length) {
+    for (const rel of drifted) console.error(`[count-chunks] DRIFT: ${rel} would restamp -> ${want}`);
+    console.error(`\n[count-chunks] --check: ${drifted.length} surface(s) drifted`);
+    process.exit(1);
+  }
+  for (const rel of drifted) console.log(`[count-chunks] ${rel}: restamped -> ${want}`);
+  console.log(`\n[count-chunks] done — ${want} chunks is the live count; ${drifted.length} surface(s) rewritten.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/scripts/described-questions.json

@@ -0,0 +1,30 @@
+[
+  { "set": "described", "query": "What should I use to coordinate a swarm of agents working in parallel?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I run several coding agents at once and have them share state and memory?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What is the best way to store and search embeddings on disk locally and privately?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "I need on-disk approximate nearest neighbor vector search with an HNSW graph. What should I use?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I give an agent persistent structured memory that survives across sessions?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What stores agent memory and lets me run graph queries over it?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I make repeated vector queries return in under a millisecond with a cache?", "expectRepo": ["rulake", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "Is there a caching layer that sits in front of a vector store to speed up recall?", "expectRepo": ["rulake", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How can I detect people, occupancy, and falls through walls using only WiFi signals and no camera?", "expectRepo": ["ruview", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I read breathing rate and heart rate contactlessly from radio signals, with no wearable?", "expectRepo": ["ruview", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I route to cheaper models automatically to cut my AI bill in Claude Code?", "expectRepo": ["agentic-flow", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What picks the cheapest good-enough model for each task automatically?", "expectRepo": ["agentic-flow", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What structured methodology should I follow to plan and build a non-trivial feature step by step?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -6 },
+  { "set": "described", "query": "Is there a phased build process with quality gates between each stage?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I get quantum-resistant secure messaging between agents?", "expectRepo": ["qudag", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What provides anonymous DAG-based communication that resists quantum attacks?", "expectRepo": ["qudag", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What gives an agent a self-aware feedback loop so it improves itself over time?", "expectRepo": ["safla", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "Is there a fast neural network library I can run in Rust or compile to WASM?", "expectRepo": ["ruv-fann", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I compress prompts to cut token cost without losing meaning?", "expectRepo": ["synthlang", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I retrieve documents using visual or page-image embeddings instead of text?", "expectRepo": ["rupixel", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What uses copy-on-write to fork and branch agent memory cheaply?", "expectRepo": ["agenticow", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I benchmark whether an agent can actually fix real security vulnerabilities?", "expectRepo": ["cve-bench", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What framework supports decentralized autonomous agents and applications?", "expectRepo": ["daa", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "Is there a TypeScript way to program and optimize LLM pipelines the way DSPy does in Python?", "expectRepo": ["dspy.ts", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What gives fast cached tool results for reliable, low-latency AI tool integration?", "expectRepo": ["fact", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "How do I scaffold, A/B test, and score different agent harnesses?", "expectRepo": ["metaharness", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "What is the building block for orchestrating parallel work across many specialized agents?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -6 },
+  { "set": "described", "query": "I want private local semantic search over my own documents. Which engine should I build on?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -6 }
+]

package/scripts/design-grade.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// design-grade.mjs — the ONLY key to the design wall (plugin/scripts/design-wall.sh).
+//
+// WHY (2026-07-16). Stuart: "You are always supposed to look at a page as an end user would: take
+// pictures of it, review it, analyze it, grade it, see if it gets a 95 or better, and if it doesn't,
+// tweak it until it does — BEFORE you ever tell me something is ready." A memory-file rule was not
+// enough ("suggestions mean bullshit"); this repo's own history says only walls hold. This tool
+// enforces the RITUAL mechanically: it refuses to record a grade unless >=2 fresh screenshots at
+// distinct widths exist and the deductions are written down. The grade itself remains judgment —
+// but the receipt (shots + deductions + number) is auditable, and the wall only opens at >=95.
+//
+// Usage:
+//   node scripts/design-grade.mjs --surface explainer --grade 96 \
+//        --shot /path/a-1440.png --shot /path/b-1920.png \
+//        --deductions "caption widowed at 1440 (-2); card border too faint in light (-2)"
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const get = (k) => { const i = args.indexOf('--' + k); return i >= 0 ? args[i + 1] : null; };
+const shots = []; args.forEach((a, i) => { if (a === '--shot') shots.push(args[i + 1]); });
+const surface = get('surface');
+const grade = Number(get('grade'));
+const deductions = get('deductions') || '';
+const fail = (m) => { console.error('✗ ' + m); process.exit(1); };
+
+if (!surface || !/^[a-z0-9-]+$/.test(surface)) fail('need --surface (kebab-case: explainer, console, readme, …)');
+if (!Number.isFinite(grade) || grade < 0 || grade > 100) fail('need a numeric --grade 0-100');
+if (shots.length < 2) fail('the ritual requires >=2 screenshots (two widths) — take them and LOOK at them first');
+if (!deductions.trim()) fail('write the deductions down — a grade with no deductions is a vibe, not a grade');
+
+const widths = new Set();
+for (const s of shots) {
+  if (!s || !fs.existsSync(s)) fail('missing screenshot: ' + s);
+  const ageMin = (Date.now() - fs.statSync(s).mtimeMs) / 60000;
+  if (ageMin > 45) fail(`stale screenshot (${ageMin | 0} min old): ${s} — the page may have changed; re-shoot`);
+  try {
+    const out = String(execFileSync('sips', ['-g', 'pixelWidth', s], { stdio: ['ignore', 'pipe', 'ignore'] }));
+    const w = Number(out.match(/pixelWidth: (\d+)/)?.[1] || 0);
+    if (w) widths.add(w);
+  } catch { /* sips unavailable → widths check degrades below */ }
+}
+if (widths.size > 0 && widths.size < 2) fail('shots must cover >=2 distinct widths (e.g. 1440 and 1920) — got: ' + [...widths].join(', '));
+
+const rec = {
+  surface, grade, passing: grade >= 95,
+  widths: [...widths].sort((a, b) => a - b),
+  shots: shots.map((s) => path.resolve(s)),
+  deductions, at: new Date().toISOString(),
+};
+const dir = path.join(os.homedir(), '.cache/ruvnet-brain');
+fs.mkdirSync(dir, { recursive: true });
+fs.appendFileSync(path.join(dir, 'design-grades.jsonl'), JSON.stringify(rec) + '\n');
+fs.writeFileSync(path.join(dir, `design-stamp-${surface}.json`), JSON.stringify(rec, null, 2) + '\n');
+console.log(`${rec.passing ? '✓ PASSING' : '✗ RECORDED — NOT PASSING'} · ${surface} graded ${grade}/100 · widths ${rec.widths.join('/') || 'unverified'} · ${shots.length} shots`);
+if (!rec.passing) { console.log('  fix the deductions and re-run — the wall stays closed below 95.'); process.exit(3); }

package/scripts/dev-plugin-link.sh

@@ -0,0 +1,105 @@
+#!/bin/sh
+# dev-plugin-link.sh — stop having to exit and restart Claude Code after every hook edit.
+#
+# THE PROBLEM. Claude Code COPIES a plugin into ~/.claude/plugins/cache/<name>/<version>/ and a
+# session pins one version directory at startup. The hook the harness executes is that copy, never
+# your working tree. So "I fixed the hook" and "the hook is fixed" are two different statements
+# until you restart. (Observed 2026-07-09: the running session's cached hook was 242 lines while
+# the repo's was 268 — a whole day of hook changes were inert.)
+#
+# WHAT DOESN'T NEED THIS. Data is already live: forge-ask-all discovers *.rvf at query time, so a
+# rebuilt KB is searchable immediately, no restart. Only CODE is pinned.
+#
+# THE FIX. Replace the cached hook scripts with a two-line shim that `exec`s the working tree's
+# copy, keeping the original as <name>.frozen.sh. The next prompt runs your edits. Reversible.
+#
+#   sh scripts/dev-plugin-link.sh --link      # working tree becomes the live hook
+#   sh scripts/dev-plugin-link.sh --status    # what is linked, what is frozen
+#   sh scripts/dev-plugin-link.sh --unlink    # restore the pristine cached copies
+#
+# SCOPE + SAFETY
+#   · Only touches ~/.claude/plugins/cache/ruvnet-brain/**/scripts/*.sh — never the repo, never
+#     settings.json, never a LaunchAgent.
+#   · The shim falls back to the frozen copy if the repo is missing, so deleting the repo cannot
+#     silently disable grounding. The harness invokes the hook with `|| true`, meaning a broken
+#     hook fails SILENTLY — hence the fallback, and hence --status.
+#   · Set RUVNET_BRAIN_DEV=0 in the environment to bypass the shim without unlinking.
+#   · This is a DEVELOPER convenience for the person who edits the plugin. Users never run it.
+#
+# The MCP server (mcp/) is a long-lived process spawned at session start; its CODE still needs that
+# process restarted. Hooks are re-exec'd per prompt, which is exactly why they can hot-reload.
+
+set -eu
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+SRC_DIR="$REPO/plugin/scripts"
+CACHE_ROOT="$HOME/.claude/plugins/cache/ruvnet-brain/ruvnet-brain"
+MODE="${1:---status}"
+
+[ -d "$SRC_DIR" ] || { echo "dev-plugin-link: no $SRC_DIR"; exit 2; }
+[ -d "$CACHE_ROOT" ] || { echo "dev-plugin-link: plugin not installed at $CACHE_ROOT"; exit 2; }
+
+# Every cached version dir — a running session may have pinned any of them, and we do not know which.
+versions() { find "$CACHE_ROOT" -mindepth 1 -maxdepth 1 -type d | sort; }
+
+is_shim() { grep -q 'RUVNET_BRAIN_DEV_SHIM' "$1" 2>/dev/null; }
+
+write_shim() {
+  target="$1"; name="$(basename "$target")"; frozen="$(dirname "$target")/${name%.sh}.frozen.sh"
+  # Freeze the pristine copy exactly once; re-linking must never overwrite it with a shim.
+  if [ ! -f "$frozen" ]; then cp "$target" "$frozen"; fi
+  cat >"$target" <<SHIM
+#!/bin/sh
+# RUVNET_BRAIN_DEV_SHIM — generated by scripts/dev-plugin-link.sh. Do not edit.
+# Delegates to the working tree so hook edits take effect on the NEXT prompt, no restart.
+DEV="$SRC_DIR/$name"
+if [ "\${RUVNET_BRAIN_DEV:-1}" = "1" ] && [ -r "\$DEV" ]; then
+  # Point CLAUDE_PLUGIN_ROOT at the repo too, so version/skills resolve from the working tree.
+  CLAUDE_PLUGIN_ROOT="$REPO/plugin"; export CLAUDE_PLUGIN_ROOT
+  exec /bin/sh "\$DEV" "\$@"
+fi
+exec /bin/sh "$(dirname "$target")/${name%.sh}.frozen.sh" "\$@"
+SHIM
+  chmod +x "$target"
+}
+
+case "$MODE" in
+  --link)
+    n=0
+    for v in $(versions); do
+      [ -d "$v/scripts" ] || continue
+      for f in "$v"/scripts/*.sh; do
+        [ -f "$f" ] || continue
+        case "$(basename "$f")" in *.frozen.sh) continue ;; esac
+        [ -f "$SRC_DIR/$(basename "$f")" ] || continue   # only shim scripts the repo actually has
+        write_shim "$f"; n=$((n + 1))
+      done
+    done
+    echo "dev-plugin-link: linked $n script(s) across $(versions | wc -l | tr -d ' ') cached version(s)"
+    echo "  live source: $SRC_DIR"
+    echo "  hook edits now apply on the NEXT prompt — no exit/restart."
+    ;;
+  --unlink)
+    n=0
+    for v in $(versions); do
+      for f in "$v"/scripts/*.frozen.sh; do
+        [ -f "$f" ] || continue
+        orig="${f%.frozen.sh}.sh"
+        mv "$f" "$orig"; n=$((n + 1))
+      done
+    done
+    echo "dev-plugin-link: restored $n pristine script(s)"
+    ;;
+  --status)
+    for v in $(versions); do
+      [ -d "$v/scripts" ] || continue
+      shimmed=0; total=0
+      for f in "$v"/scripts/*.sh; do
+        case "$(basename "$f")" in *.frozen.sh) continue ;; esac
+        total=$((total + 1)); is_shim "$f" && shimmed=$((shimmed + 1))
+      done
+      printf '  %-14s %s/%s shimmed\n' "$(basename "$v")" "$shimmed" "$total"
+    done
+    ;;
+  *) echo "usage: dev-plugin-link.sh [--link|--unlink|--status]"; exit 2 ;;
+esac

package/scripts/distill-project.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * distill-project.mjs — the ONE genuinely offerable capability, made genuinely reversible.
+ *
+ * WHY THIS FILE EXISTS. ADR-047 proposed a system for offering dormant capabilities to the user
+ * unprompted. Both duelists rejected it, and GPT-5.6-Sol's arithmetic is the reason: the registry has
+ * five `turnOn` commands and ZERO verified inverses, so the honest launch surface was **zero**. Its
+ * one claimed exception — memory distillation — sourced its undo from `remedy-registry.mjs`'s
+ * RESTORE_STORE_BACKUPS, which restores snapshots that `health-repair.mjs --distill-fleet` takes,
+ * while the OFFER handed the user raw `ruflo memory distill run`. Verified against `--help`: that
+ * command has no backup option at all. **The offered action and the promised inverse were two
+ * different execution paths.**
+ *
+ * An undo promise with no branch behind the action actually offered is this repo's origin sin. So
+ * before any delivery system gets built, one capability has to be safe end to end. This is that one.
+ *
+ * WHAT IT IS NOT. It is not a reimplementation of distillation, and it does not hand-roll a backup.
+ * `ruflo memory backup` is rUv's own snapshot and its `--help` states it is "WAL-safe, rotated" —
+ * which matters, because `cp` on a live WAL database silently amputates the newest transactions (this
+ * project has already lost data that way once). This file is a WRAPPER that sequences rUv's real
+ * commands in the order that makes the operation reversible, and refuses to proceed when it cannot.
+ *
+ * THE SEQUENCE, and every step is there because skipping it breaks a guarantee:
+ *
+ *   1. status BEFORE     — the delta is meaningless without it, and "it worked" is unfalsifiable.
+ *   2. WAL-safe snapshot — rUv's `memory backup --db --dir`. This is the undo. No snapshot, no run.
+ *   3. receipt, FAIL-CLOSED — written and fsync'd BEFORE the mutation. `health-repair.mjs:185`
+ *      catches its own receipt-write failure and distills anyway; that is how a mutation happens with
+ *      no durable record of where its undo lives. Here a receipt that cannot be written ABORTS.
+ *   4. distill run --db  — project-scoped, `--budget-usd 0` (the default), so nothing paid can fire.
+ *   5. status AFTER + delta — verified, and reported as a measurement rather than a verdict.
+ *   6. receipt completed — the same file, updated with the outcome and the exact restore command.
+ *
+ * `--restore <snapshot>` is the inverse, and it is tested. An undo nobody has run is a promise.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const HOME = os.homedir();
+const RUFLO = process.env.RUFLO_BIN || path.join(HOME, '.npm-global/bin/ruflo');
+const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
+
+const argv = process.argv.slice(2);
+const arg = (f, d) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+const has = (f) => argv.includes(f);
+
+const PROJECT = path.resolve(arg('--project', process.cwd()));
+const DB = path.resolve(arg('--db', path.join(PROJECT, '.swarm', 'memory.db')));
+const BACKUP_DIR = path.resolve(arg('--backup-dir', path.join(PROJECT, '.swarm', 'backups')));
+const RECEIPTS = path.join(HOME, '.cache', 'ruvnet-brain', 'distill-receipts.jsonl');
+const DRY = has('--dry-run');
+
+const say = (s) => process.stdout.write(s + '\n');
+const die = (s, code = 1) => { process.stderr.write(s + '\n'); process.exit(code); };
+
+/** Run a ruflo subcommand, returning {ok, out, err}. Never throws — callers decide what a failure means. */
+function ruflo(args, { timeout = 600_000 } = {}) {
+  const r = spawnSync(RUFLO, args, { encoding: 'utf8', timeout, env: RUFLO_ENV, shell: process.platform === 'win32' }); // a global npm ruflo is ruflo.cmd on Windows; Node refuses .cmd without a shell (CVE-2024-27980)
+  return { ok: !r.error && r.status === 0, out: r.stdout || '', err: (r.stderr || '') + (r.error ? String(r.error.message) : '') };
+}
+
+/**
+ * Read the distilled-table counts. Parsed from `memory distill status`, and a parse failure is
+ * reported as UNKNOWN rather than 0 — a fabricated zero here would turn "we could not read it" into
+ * "there was nothing", which is the exact lie this repo's registry rule exists to kill.
+ */
+function distillCounts() {
+  const r = ruflo(['memory', 'distill', 'status', '--db', DB], { timeout: 120_000 });
+  if (!r.ok) return { readable: false, why: r.err.trim().split('\n')[0] || 'distill status failed', raw: r.out };
+  const num = (label) => {
+    const m = new RegExp(`${label}[^0-9]{0,40}(\\d[\\d,]*)`, 'i').exec(r.out);
+    return m ? Number(m[1].replace(/,/g, '')) : null;
+  };
+  return {
+    readable: true,
+    patterns: num('reasoning_patterns') ?? num('patterns'),
+    episodes: num('episodes'),
+    raw: r.out.trim(),
+  };
+}
+
+/** Append a receipt line, fsync'd. Returns false if it cannot be durably written — the caller ABORTS. */
+function writeReceipt(rec) {
+  try {
+    fs.mkdirSync(path.dirname(RECEIPTS), { recursive: true });
+    const fd = fs.openSync(RECEIPTS, 'a');
+    try { fs.writeSync(fd, JSON.stringify(rec) + '\n'); fs.fsyncSync(fd); }
+    finally { fs.closeSync(fd); }
+    return true;
+  } catch { return false; }
+}
+
+/** The newest snapshot this project has, or null. Used to tell the user what `--restore` would take. */
+function newestSnapshot() {
+  try {
+    const files = fs.readdirSync(BACKUP_DIR)
+      .filter((f) => /\.(db|sqlite|bak)$/i.test(f) || /memory.*\d/.test(f))
+      .map((f) => ({ f, p: path.join(BACKUP_DIR, f), t: fs.statSync(path.join(BACKUP_DIR, f)).mtimeMs }))
+      .sort((a, b) => b.t - a.t);
+    return files.length ? files[0].p : null;
+  } catch { return null; }
+}
+
+// ── RESTORE — the inverse. Deliberately first, because an undo you cannot reach is not an undo. ────
+if (has('--restore')) {
+  const snap = arg('--restore', null) || newestSnapshot();
+  if (!snap) die(`no snapshot to restore from — looked in ${BACKUP_DIR.replace(HOME, '~')}`);
+  if (!fs.existsSync(snap)) die(`snapshot not found: ${snap}`);
+  if (DRY) { say(`[dry-run] would restore ${snap.replace(HOME, '~')} → ${DB.replace(HOME, '~')}`); process.exit(0); }
+
+  // Snapshot the CURRENT state before overwriting it. Restoring is itself a mutation, and an undo
+  // that destroys the thing it replaces leaves the user with no way back if they restored by mistake.
+  const pre = path.join(BACKUP_DIR, `pre-restore-${Date.now()}.db`);
+  try { fs.mkdirSync(BACKUP_DIR, { recursive: true }); fs.copyFileSync(DB, pre); }
+  catch (e) { die(`refusing to restore — could not snapshot the current DB first (${e.message})`); }
+
+  try { fs.copyFileSync(snap, DB); }
+  catch (e) { die(`restore FAILED (${e.message}). Your pre-restore copy is at ${pre.replace(HOME, '~')}`); }
+
+  writeReceipt({ at: new Date().toISOString(), action: 'restore', db: DB, from: snap, preRestore: pre });
+  say(`restored ${snap.replace(HOME, '~')} → ${DB.replace(HOME, '~')}`);
+  say(`the state you replaced is at ${pre.replace(HOME, '~')} if you need it back`);
+  process.exit(0);
+}
+
+// ── PRE-FLIGHT ─────────────────────────────────────────────────────────────────────────────────────
+if (!fs.existsSync(RUFLO)) die(`ruflo is not at ${RUFLO.replace(HOME, '~')} — install it with \`npm i -g ruflo@latest\``);
+if (!fs.existsSync(DB)) die(`no memory store at ${DB.replace(HOME, '~')} — nothing to distill for this project`);
+
+say(`project : ${PROJECT.replace(HOME, '~')}`);
+say(`store   : ${DB.replace(HOME, '~')}`);
+
+const before = distillCounts();
+if (!before.readable) {
+  // Refuse rather than guess. A delta computed from an unreadable baseline is a fabricated number.
+  die(`cannot read distill status for this store (${before.why}) — refusing to run, because without a baseline the result would be unverifiable`);
+}
+say(`before  : ${before.patterns ?? '?'} patterns, ${before.episodes ?? '?'} episodes`);
+
+if (DRY) {
+  const r = ruflo(['memory', 'distill', 'run', '--db', DB, '--dry-run']);
+  say('');
+  say(r.out.trim() || '(no dry-run output)');
+  say('');
+  say('[dry-run] nothing was written, and no snapshot was taken.');
+  process.exit(r.ok ? 0 : 1);
+}
+
+// ── 1. SNAPSHOT FIRST. This is the undo; without it the operation is not offerable. ────────────────
+say('snapshot: taking a WAL-safe copy via `ruflo memory backup` before touching anything…');
+const bk = ruflo(['memory', 'backup', '--db', DB, '--dir', BACKUP_DIR]);
+if (!bk.ok) {
+  die(`REFUSING TO DISTILL — the snapshot failed (${bk.err.trim().split('\n')[0] || 'unknown error'}).\n`
+    + 'This is deliberate: distillation without a verified undo is exactly the unsafe offer this wrapper exists to prevent.');
+}
+const snapshot = newestSnapshot();
+if (!snapshot) die('REFUSING TO DISTILL — `memory backup` reported success but no snapshot file is present, so the undo cannot be located.');
+say(`snapshot: ${snapshot.replace(HOME, '~')}`);
+
+// ── 2. RECEIPT, FAIL-CLOSED, BEFORE THE MUTATION. ─────────────────────────────────────────────────
+// health-repair.mjs:185 catches its own receipt-write failure and distills anyway. That is how a
+// mutation happens with no durable record of where its undo lives. Here, no receipt means no run.
+const startedAt = new Date().toISOString();
+if (!writeReceipt({ at: startedAt, action: 'distill:start', db: DB, snapshot, before: { patterns: before.patterns, episodes: before.episodes } })) {
+  die(`REFUSING TO DISTILL — could not durably write a receipt to ${RECEIPTS.replace(HOME, '~')}.\n`
+    + 'A mutation with no record of its undo is worse than no mutation. Fix the path and re-run.');
+}
+
+// ── 3. THE ACTUAL WORK — rUv's command, project-scoped, $0 by default. ────────────────────────────
+say('distill : running `ruflo memory distill run` against this project only…');
+const run = ruflo(['memory', 'distill', 'run', '--db', DB]);
+if (run.out.trim()) say(run.out.trim());
+
+// ── 4. VERIFY THE DELTA. A measurement, not a verdict. ────────────────────────────────────────────
+const after = distillCounts();
+const delta = (before.readable && after.readable && before.patterns != null && after.patterns != null)
+  ? after.patterns - before.patterns : null;
+
+const outcome = {
+  at: new Date().toISOString(), action: 'distill:done', db: DB, snapshot, startedAt,
+  ok: run.ok,
+  before: { patterns: before.patterns, episodes: before.episodes },
+  after: after.readable ? { patterns: after.patterns, episodes: after.episodes } : { unreadable: after.why },
+  deltaPatterns: delta,
+  restore: `node ${path.join(path.dirname(new URL(import.meta.url).pathname))}/distill-project.mjs --restore ${snapshot}`,
+};
+writeReceipt(outcome);
+
+say('');
+if (!run.ok) {
+  say(`distill did NOT complete cleanly: ${run.err.trim().split('\n')[0] || 'unknown error'}`);
+  say(`your store is unchanged or partially changed; restore with:\n  ${outcome.restore}`);
+  process.exit(1);
+}
+if (delta === null) say('after   : counts could not be re-read, so the change is UNVERIFIED — the snapshot above is still your undo.');
+else if (delta > 0) say(`after   : ${after.patterns} patterns (+${delta}) — measured, not asserted.`);
+else say(`after   : ${after.patterns} patterns (no change). Distillation ran and found nothing new to mine; that is a real answer, not a failure.`);
+say(`undo    : ${outcome.restore}`);