ruvnet-brain 4.3.8 → 4.3.10

package/scripts/claims-verify.mjs

@@ -9,7 +9,7 @@
 //
 // Usage:  node scripts/claims-verify.mjs        (or: npm run claims:verify)  — READ-ONLY gate
 //         node scripts/claims-verify.mjs --fix  (or: npm run claims:fix)     — regenerate the surfaces
-// Exit:   0 = every claim regenerated (skips allowed, printed); 1 = any claim failed.
+// Exit: 0 = completed diagnostic; 1 = failed claim; --strict additionally exits 4 on UNKNOWN.
 //
 // Verify functions take artifact paths as parameters (repo paths as defaults) so tests can
 // point them at tampered copies. Main-guarded like scripts/eval-brain.mjs so tests can import
@@ -18,8 +18,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
+import os from 'node:os';
+import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { storeRoot } from '../kb/store-root.mjs';
+import { validateCoverageDirectory, sha256File } from './coverage-integrity.mjs';
+import { verifyPayload, verifyPayloadMembers, payloadIdFor } from './release-payload.mjs';
+import { extractZip } from '../kb/zip-extract.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -110,10 +116,12 @@ export function verifyHeldOutStrata(file = path.join(ROOT, 'evals', 'held-out.js
 // (with the 51.33 figure alongside it). ~56× = $15 / $0.267 ≈ 56.2. We re-find both corpus
 // strings with a plain streaming grep (first match wins) and re-do the arithmetic. The passages
 // file ships with the 512MB brain, which CI does not have — absent file is a LOUD SKIP, never
-// a silent pass.
-export async function verifyCheaperFactor(file = path.join(ROOT, 'kb', 'metaharness.passages.jsonl')) {
+// a silent pass. Default reads the canonical store root (kb/store-root.mjs), not <repo>/kb — that
+// directory is a gitignored build workspace the installed brain never lands in (see kbDir on the
+// census functions below for the same fix).
+export async function verifyCheaperFactor(file = path.join(storeRoot(), 'metaharness.passages.jsonl')) {
   if (!fs.existsSync(file)) {
-    return skip(`brain not installed — ${path.relative(ROOT, file)} absent, cannot re-derive ~56× from corpus (runs on machines with the brain)`);
+    return skip(`brain not installed — ${file} absent, cannot re-derive ~56× from corpus (runs on machines with the brain)`);
   }
 
   const needles = ['$0.267', '51.33'];
@@ -368,11 +376,21 @@ export async function verifyCoverageBadge(
 // the fence). Every user-facing surface that quotes the number must quote THIS number — the count
 // sat at a stale 128,994 across 10+ surfaces after a rebuild moved it (2026-07-10 gremlin hunt).
 // The sidecars ship with the brain, which bare CI does not have — absent kb dir is a LOUD SKIP.
+//
+// kbDir (where the idmap sidecars live) and the private-stores fence are two DIFFERENT facts, same
+// conflation kb/store-root.mjs's header names: the fence is a small policy file this repo commits at
+// a fixed path (scripts/build-bundle.mjs reads the identical path), while the sidecars ship with the
+// installed brain at the canonical store root (kb/store-root.mjs's storeRoot(), not <repo>/kb — that
+// directory is a gitignored build workspace the installed brain never lands in outside the release
+// build's own KB_DIR override, which storeRoot() already honors). Defaulting kbDir to
+// `path.join(ROOT, 'kb')` — the exact anti-pattern kb/forge-currency.mjs's brainKnownSet() carried
+// until PR #222 — made this check silently SKIP on any machine with a real installed brain outside
+// the repo checkout, never re-deriving the count it exists to police.
 export const CHUNK_SURFACES = ['README.md', 'explainer/index.html', 'explainer/llms.txt', 'explainer/llms-full.txt'];
+export const PRIVATE_STORES_FILE = path.join(ROOT, 'kb', 'PRIVATE-STORES.json');
 
-export function computePublicChunkTotal(kbDir = path.join(ROOT, 'kb')) {
-  const privFile = path.join(kbDir, 'PRIVATE-STORES.json');
-  const priv = new Set(fs.existsSync(privFile) ? JSON.parse(fs.readFileSync(privFile, 'utf8')).privateStores : []);
+export function computePublicChunkTotal(kbDir = storeRoot(), privateStoresFile = PRIVATE_STORES_FILE) {
+  const priv = new Set(fs.existsSync(privateStoresFile) ? JSON.parse(fs.readFileSync(privateStoresFile, 'utf8')).privateStores : []);
   let total = 0, stores = 0;
   for (const f of fs.readdirSync(kbDir)) {
     const m = f.match(/^(.+)\.big\.rvf\.idmap\.json$/);
@@ -384,13 +402,13 @@ export function computePublicChunkTotal(kbDir = path.join(ROOT, 'kb')) {
 }
 
 /** Every built store on disk, private ones included — what "N built stores incl. private" advertises. */
-export function countBuiltStores(kbDir = path.join(ROOT, 'kb')) {
+export function countBuiltStores(kbDir = storeRoot()) {
   return fs.readdirSync(kbDir).filter((f) => /\.big\.rvf\.idmap\.json$/.test(f)).length;
 }
 
 /** The three brain census numbers every public surface quotes, all from the same artifacts. */
-export function brainCensus(kbDir = path.join(ROOT, 'kb')) {
-  const { total, stores } = computePublicChunkTotal(kbDir);
+export function brainCensus(kbDir = storeRoot(), privateStoresFile = PRIVATE_STORES_FILE) {
+  const { total, stores } = computePublicChunkTotal(kbDir, privateStoresFile);
   return { chunks: total, publicStores: stores, builtStores: countBuiltStores(kbDir) };
 }
 
@@ -409,11 +427,11 @@ export const SURFACE_CLAIM_RULES = [
 
 const fmtNum = (n, fmt) => (fmt === 'comma' ? n.toLocaleString('en-US') : String(n));
 
-export function verifyChunkCountSurfaces(kbDir = path.join(ROOT, 'kb'), surfaces = CHUNK_SURFACES, root = ROOT) {
+export function verifyChunkCountSurfaces(kbDir = storeRoot(), surfaces = CHUNK_SURFACES, root = ROOT, privateStoresFile = PRIVATE_STORES_FILE) {
   if (!fs.existsSync(kbDir) || !fs.readdirSync(kbDir).some((f) => f.endsWith('.big.rvf.idmap.json'))) {
-    return skip('brain not installed — kb/*.big.rvf.idmap.json absent, cannot re-derive the chunk count (runs on machines with the brain)');
+    return skip(`brain not installed — ${path.join(kbDir, '*.big.rvf.idmap.json')} absent, cannot re-derive the chunk count (runs on machines with the brain)`);
   }
-  const census = brainCensus(kbDir);
+  const census = brainCensus(kbDir, privateStoresFile);
   const want = census.chunks.toLocaleString('en-US');
 
   const problems = [];
@@ -490,7 +508,8 @@ function restampRule(s, rule, value) {
 
 export async function applyFix({
   root = ROOT,
-  kbDir = path.join(root, 'kb'),
+  kbDir = storeRoot(),
+  privateStoresFile = PRIVATE_STORES_FILE,
   surfaces = CHUNK_SURFACES,
   readmeFile = path.join(root, 'README.md'),
   summaryFile = path.join(root, 'coverage', 'coverage-summary.json'),
@@ -512,7 +531,7 @@ export async function applyFix({
   if (!haveBrain) {
     report.notes.push('brain not installed — chunk/store counts left untouched (nothing to re-derive them from)');
   } else {
-    const census = brainCensus(kbDir);
+    const census = brainCensus(kbDir, privateStoresFile);
     report.census = census;
     for (const rel of surfaces) {
       const { p, s } = readSurface(rel);
@@ -615,59 +634,214 @@ export async function verifyLearningReplay() {
 // ── the ledger ──────────────────────────────────────────────────────────────────────────────────
 export const ledger = [
   {
+    id: 'baseline', scope: 'source',
     claim: 'grounded 12/12 → n=120 baseline',
     source: 'evals/baseline.json',
     verify: verifyBaseline,
   },
   {
     claim: 'held-out set is frozen at 120 questions across 5 strata',
+    id: 'held-out', scope: 'source',
     source: 'evals/held-out.json',
     verify: verifyHeldOutStrata,
   },
   {
     claim: '~56× cheaper (explainer + hook)',
+    id: 'cost-factor', scope: 'runtime',
     source: 'kb/metaharness.passages.jsonl',
     verify: verifyCheaperFactor,
   },
   {
     claim: 'coverage badge % re-derives from the real coverage run (ALL source)',
+    id: 'coverage', scope: 'source',
     source: 'README.md + coverage/coverage-summary.json + vitest.config.mjs',
     verify: verifyCoverageBadge,
   },
   {
     claim: 'version surfaces agree',
+    id: 'version', scope: 'source',
     source: 'scripts/sync-version.mjs --check',
     verify: verifyVersionSurfaces,
   },
   {
     claim: 'advertised source-chunk count regenerates from the brain (all surfaces agree)',
+    id: 'chunk-count', scope: 'runtime',
     source: 'kb/*.big.rvf.idmap.json + kb/PRIVATE-STORES.json',
     verify: verifyChunkCountSurfaces,
   },
   // The invariant vector rides the same runner so it is printed in the same table and obeys the same
   // "a skip is never a silent pass" rule. The vector is ALSO exported separately (`invariants`) so a
   // future release gate can consume the named states without reading prose out of a markdown row.
-  ...invariants.map((iv) => ({ claim: `invariant ${iv.name}: ${iv.what}`, source: iv.source, verify: iv.verify })),
+  ...invariants.map((iv) => ({ id: iv.name, scope: 'runtime', claim: `invariant ${iv.name}: ${iv.what}`, source: iv.source, verify: iv.verify })),
 ];
 
+export function claimsScope(scope = 'all') {
+  if (!['all', 'source', 'runtime'].includes(scope)) throw new Error(`unknown claims scope: ${scope}`);
+  const entries = ledger.filter((entry) => scope === 'all' || entry.scope === scope);
+  return { scope, complete: scope === 'all', entries, omitted: ledger.filter((entry) => !entries.includes(entry)).map(({ id }) => id) };
+}
+
 // ── runner ──────────────────────────────────────────────────────────────────────────────────────
 const cell = (s) => String(s).replaceAll('|', '\\|');
 
-export async function runLedger(entries = ledger) {
+async function qualifyCensusArtifacts({ candidateKb, candidateSha, candidateVersion, candidateRoot,
+  payloadManifest, payloadSignature, payloadId, qualificationMode, publicKey }, checked, members, census) {
+  if (!['signed', 'staged'].includes(qualificationMode)) throw new Error('runtime qualification mode must be signed or staged');
+  const required = [payloadManifest, payloadId, candidateRoot, ...(qualificationMode === 'signed' ? [payloadSignature] : [])];
+  if (required.some((value) => !value) || !fs.existsSync(payloadManifest)
+    || (qualificationMode === 'signed' && !fs.existsSync(payloadSignature))) return null;
+  const regularFile = (file) => {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('runtime artifact must be a regular non-symlink file');
+    return file;
+  };
+  const manifest = JSON.parse(fs.readFileSync(regularFile(payloadManifest), 'utf8'));
+  if (manifest.candidateSha !== candidateSha || manifest.version !== candidateVersion || manifest.tag !== `v${candidateVersion}`
+    || payloadIdFor(manifest) !== payloadId) throw new Error('runtime payload identity differs from the explicit candidate');
+  const root = path.dirname(fs.realpathSync(payloadManifest));
+  const byRole = (role) => {
+    const matches = manifest.members?.filter((member) => member.role === role) || [];
+    if (matches.length !== 1) throw new Error(`runtime payload requires exactly one ${role} member`);
+    return matches[0];
+  };
+  const npm = byRole('npm'), bundle = byRole('bundle');
+  for (const member of manifest.members) {
+    if (!member.name || path.basename(member.name) !== member.name) throw new Error('unsafe runtime payload member name');
+    regularFile(path.join(root, member.name));
+  }
+  const verify = () => qualificationMode === 'signed'
+    ? verifyPayload({ manifest, root, signature: fs.readFileSync(regularFile(payloadSignature), 'utf8'),
+      publicKey: publicKey || crypto.createPublicKey(fs.readFileSync(path.join(ROOT, 'keys/ruvnet-brain-signing.pub.pem'))) })
+    : verifyPayloadMembers({ manifest, root });
+  verify();
+  // The source validator is shared with release recovery. Read committed surface bytes below:
+  // untracked lookalikes must never supply the advertising proof.
+  const { validateCandidateSource } = await import('./publication-receipt.mjs');
+  validateCandidateSource(candidateRoot, { sha: candidateSha, version: candidateVersion });
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'claims-bound-artifacts-'));
+  try {
+    const extracted = await extractZip(path.join(root, bundle.name), temp);
+    const coverageFiles = extracted.entryNames.filter((name) => path.posix.basename(name) === 'COVERAGE.json');
+    if (coverageFiles.length !== 1) throw new Error('runtime bundle must contain exactly one release coverage projection');
+    const archiveRoot = path.dirname(path.join(temp, coverageFiles[0]));
+    const bound = validateCoverageDirectory(archiveRoot, { expectedVersion: candidateVersion,
+      expectedSourceSnapshot: candidateSha, requireCompleteProfile: true });
+    if (!bound.valid) throw new Error(`runtime archive projection rejected: ${bound.failures.join('; ')}`);
+    if (bound.coverageSha256 !== checked.coverageSha256) throw new Error('runtime projection differs from the bound bundle');
+    const sidecars = [];
+    let boundChunks = 0;
+    for (const name of members) {
+      const installed = regularFile(path.join(candidateKb, name));
+      const archived = regularFile(path.join(archiveRoot, name));
+      const bytes = fs.readFileSync(archived);
+      const hash = crypto.createHash('sha256').update(bytes).digest('hex');
+      const { idToLabel } = JSON.parse(bytes);
+      if (!idToLabel || typeof idToLabel !== 'object' || Array.isArray(idToLabel)) throw new Error('bound public sidecar has invalid idToLabel');
+      boundChunks += Object.keys(idToLabel).length;
+      if (sha256File(installed) !== hash) throw new Error(`runtime public sidecar differs from the bound bundle: ${name}`);
+      sidecars.push({ file: name, sha256: hash, bytes: bytes.length });
+    }
+    if (boundChunks !== census.chunks) throw new Error('runtime public count changed before artifact binding');
+    const expected = { ...census, builtStores: census.publicStores };
+    const problems = [];
+    for (const file of CHUNK_SURFACES) {
+      const result = spawnSync('git', ['show', `${candidateSha}:${file}`], { cwd: candidateRoot, encoding: 'utf8' });
+      if (result.status !== 0) throw new Error(`candidate source lacks tracked claim surface: ${file}`);
+      const text = result.stdout;
+      if (!text.includes(census.chunks.toLocaleString('en-US'))) problems.push(`${file}: candidate chunk count absent`);
+      for (const rule of SURFACE_CLAIM_RULES) for (const match of text.matchAll(rule.re)) for (const group of rule.groups) {
+        if (Number(match[group.i].replace(/,/g, '')) !== expected[rule.key]) problems.push(`${file}: candidate ${rule.name} differs`);
+      }
+    }
+    if (problems.length) throw new Error(problems.join('; '));
+    validateCandidateSource(candidateRoot, { sha: candidateSha, version: candidateVersion });
+    for (const sidecar of sidecars) {
+      if (sha256File(regularFile(path.join(candidateKb, sidecar.file))) !== sidecar.sha256) {
+        throw new Error('runtime public sidecar changed during qualification');
+      }
+    }
+    verify();
+    return { payloadId, signatureVerified: qualificationMode === 'signed', packageSha256: npm.sha256,
+      bundleSha256: bundle.sha256, sidecarsVerified: sidecars.length, sidecars,
+      claimSourceSha: candidateSha, surfacesVerified: CHUNK_SURFACES.length, publicChunks: boundChunks };
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+
+// Ambient counts are diagnostic. Qualification requires explicit candidate artifacts and source.
+export async function verifyRuntimeCensus({ candidateKb = null, candidateSha = null,
+  candidateVersion = null, diagnosticKb = storeRoot(), privateStoresFile = PRIVATE_STORES_FILE,
+  candidateRoot = null, payloadManifest = null, payloadSignature = null, payloadId = null,
+  qualificationMode = 'signed', publicKey = null } = {}) {
+  const diagnostics = { ambient: { root: path.resolve(diagnosticKb), diagnostic: true } };
+  try { diagnostics.ambient.census = brainCensus(diagnosticKb, privateStoresFile); }
+  catch (error) { diagnostics.ambient.error = error.message; }
+  const provenance = { projectionVerified: false, candidate: {
+    root: candidateKb ? path.resolve(candidateKb) : null, sourceSha: candidateSha, version: candidateVersion,
+  } };
+  const details = { diagnostic: true, qualification: 'UNKNOWN', diagnostics, provenance,
+    untested: ['signed package/bundle-to-sidecar binding'] };
+  if (!candidateKb || !candidateSha || !candidateVersion) {
+    return { ...skip('Runtime qualification requires explicit candidate KB, source SHA, and version; ambient census is diagnostic only.'), ...details };
+  }
+  try {
+    const checked = validateCoverageDirectory(candidateKb, { expectedVersion: candidateVersion,
+      expectedSourceSnapshot: candidateSha, requireCompleteProfile: true });
+    if (!checked.valid) return { ...fail(`Candidate projection rejected: ${checked.failures.join('; ')}`), ...details };
+    provenance.projectionVerified = true;
+    provenance.candidate.coverageSha256 = checked.coverageSha256;
+    provenance.candidate.publicGenerationLedgerSha256 = sha256File(path.join(candidateKb, 'PUBLIC-RVF-GENERATIONS.json'));
+    const members = new Set(checked.publicInventory.publicStores.map((store) => `${store}.big.rvf.idmap.json`));
+    let chunks = 0;
+    for (const name of members) {
+      const file = path.join(candidateKb, name);
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${name} is not a regular census sidecar`);
+      const { idToLabel } = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (!idToLabel || typeof idToLabel !== 'object' || Array.isArray(idToLabel)) throw new Error(`${name} has invalid idToLabel`);
+      chunks += Object.keys(idToLabel).length;
+    }
+    const extraSidecars = fs.readdirSync(candidateKb)
+      .filter((name) => name.endsWith('.big.rvf.idmap.json') && !members.has(name)).length;
+    diagnostics.candidate = { chunks, publicStores: members.size, extraSidecars };
+    const artifacts = await qualifyCensusArtifacts({ candidateKb, candidateSha, candidateVersion, candidateRoot,
+      payloadManifest, payloadSignature, payloadId, qualificationMode, publicKey }, checked, members, diagnostics.candidate);
+    if (artifacts) {
+      provenance.artifacts = artifacts;
+      return { ...pass(`Exact ${qualificationMode} candidate public census and ${CHUNK_SURFACES.length} committed claim surfaces agree.`),
+        ...details, diagnostic: false, qualification: `${qualificationMode}-candidate`,
+        untested: [qualificationMode === 'staged' ? 'signed public publication proof' : 'public installation and channel convergence'] };
+    }
+    return { ...skip('Public projection verified; census remains diagnostic: signed package/bundle-to-sidecar binding is untested.'), ...details };
+  } catch (error) {
+    return { ...fail(`Candidate census rejected: ${error.message}`), ...details };
+  }
+}
+
+export async function runLedger(entries = ledger, { strict = false, runtimeCensus = {} } = {}) {
   const rows = [];
   for (const entry of entries) {
     let result;
     try {
-      result = await entry.verify();
+      result = entry.id === 'chunk-count' && strict
+        ? await verifyRuntimeCensus(runtimeCensus) : await entry.verify();
+      if (entry.id === 'chunk-count' && !strict) result = { ...result, diagnostic: true,
+        qualification: 'UNKNOWN', provenance: { mode: 'ambient-diagnostic', root: storeRoot() } };
     } catch (e) {
       result = fail(`verify() threw: ${e.message}`);
     }
-    rows.push({ claim: entry.claim, source: entry.source, ...result });
+    rows.push({ id: entry.id, claim: entry.claim, source: entry.source, ...result });
   }
   return rows;
 }
 
+export function claimsVerdict(rows) {
+  if (rows.some(({ status }) => status === FAIL)) return FAIL;
+  return rows.length && rows.every(({ status }) => status === PASS) ? PASS : 'UNKNOWN';
+}
+
 async function main() {
+  const strict = process.argv.includes('--strict');
+  if (strict && process.argv.includes('--fix')) throw new Error('--strict qualification cannot rewrite advertising from an ambient census');
   // --fix is the ONLY writing path; the gate itself never mutates a surface.
   if (process.argv.includes('--fix')) {
     const report = await applyFix({ write: true });
@@ -686,7 +860,29 @@ async function main() {
     console.log('');
   }
 
-  const rows = await runLedger();
+  const scopeIndex = process.argv.indexOf('--scope');
+  if (scopeIndex >= 0 && !process.argv[scopeIndex + 1]) throw new Error('--scope requires all, source, or runtime');
+  const selected = claimsScope(scopeIndex < 0 ? 'all' : process.argv[scopeIndex + 1]);
+  const option = (name) => {
+    const index = process.argv.indexOf(name);
+    if (index < 0) return null;
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value`);
+    return value;
+  };
+  const rows = await runLedger(selected.entries, { strict, runtimeCensus: {
+    candidateKb: option('--candidate-kb'), candidateSha: option('--candidate-sha'),
+    candidateVersion: option('--candidate-version'),
+    candidateRoot: option('--candidate-root'), payloadManifest: option('--payload-manifest'),
+    payloadSignature: option('--payload-signature'), payloadId: option('--payload-id'),
+    qualificationMode: option('--qualification-mode') || 'signed',
+  } });
+  const scopeVerdict = claimsVerdict(rows);
+  const receipt = { schema: 'ruvnet-brain.claims', scope: selected.scope, complete: selected.complete,
+    verdict: scopeVerdict === FAIL || selected.complete ? scopeVerdict : 'UNKNOWN', scopeVerdict, omitted: selected.omitted, rows };
+  console.log(JSON.stringify(receipt));
+  const reportIndex = process.argv.indexOf('--report');
+  if (reportIndex >= 0) fs.writeFileSync(process.argv[reportIndex + 1], JSON.stringify(receipt, null, 2), { flag: 'wx' });
 
   console.log('## Claims ledger — every advertised number must regenerate from an artifact\n');
   console.log('| claim | status | evidence |');
@@ -702,7 +898,9 @@ async function main() {
     console.error(`\nclaims:verify FAILED — ${failed.length} claim(s) no longer regenerate from their artifacts.`);
     process.exit(1);
   }
-  console.log(`\nclaims:verify OK — ${rows.length - skipped.length} verified, ${skipped.length} skipped (loudly).`);
+  const verdict = claimsVerdict(rows);
+  console.log(`\nclaims:verify scope=${selected.scope} ${verdict} — ${rows.length - skipped.length} verified, ${skipped.length} unmeasured; omitted=${selected.omitted.join(',') || 'none'}.`);
+  if (verdict === 'UNKNOWN' && process.argv.includes('--strict')) process.exitCode = 4;
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/scripts/console-engine.mjs

@@ -216,24 +216,10 @@ export function buildHealthRecommendations({ memory = null, learning = null } =
 // "here is the gap" to "here is the one-click fix" — the exact gap ADR-027 closed for health/stack/
 // wiring findings, left open for capabilities.
 //
-// THE BAR IS HIGHER THAN "has a turnOn command". capability-registry.mjs's own header states turnOn
-// is null unless the exact command was verified with --help — that proves the command EXISTS, not
-// that its INVERSE has ever been run. Of the registry's rows, only `memory-distillation` clears both:
-// distill-project.mjs's header records a live, round-tripped proof (644 → 648 patterns, restore →
-// 644, re-run → 648, 2026-07-24) — an undo that has actually executed, not merely been promised in a
-// comment (see that file's header for why "promised, never run" was this project's origin sin).
-//
-// So this is a small, explicit map, not "every row with a non-null turnOn". A second and third
-// capability (most likely cross-project-lessons, then workflow-pattern-learning) join this map only
-// once THEIR undo is independently proven the same way — never before (Rule 0: verify, don't assume).
-const CAPABILITY_ELIGIBLE = {
-  'memory-distillation': {
-    title: 'Turn on memory distillation',
-    scope: 'project',
-    cost: { time: '~10s', usd: 0, risk: 'low' },
-    undo: { human: 'restores the pre-distill snapshot exactly (proven 2026-07-24: 644→648 patterns, restore→644, re-run→648)' },
-  },
-};
+// A historical restore demonstration is not proof of a currently available inverse.
+// distill-project --restore now refuses unsafe database replacement, so memory-distillation
+// is not offerable. Keep the allowlist empty until an inverse is available and verified.
+const CAPABILITY_ELIGIBLE = {};
 
 /**
  * @param {{ capabilities?: Array<{key,label,state,scope,turnOn,evidence,whatItBuysYou}> }} input — the

package/scripts/console-runtime-identity.mjs

@@ -38,6 +38,12 @@ export const CONSOLE_RUNTIME_SURFACE = Object.freeze([
   'plugin/.claude-plugin',
   'data/model-catalog.json',
   'kb/brain-profile.mjs',
+  // The staged installer imports these helpers, including ZIP extraction on its update path.
+  // Keep their bytes in the same copy/digest authority as the installer itself.
+  'kb/refresh-run.mjs',
+  'kb/lifecycle-evidence-retention.mjs',
+  'kb/model-requirements.mjs',
+  'kb/zip-extract.mjs',
   'bin/install.mjs',
   'package.json',
 ]);

package/scripts/development-maintenance.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { maintenanceStatus } from '../plugin/scripts/development-maintenance.mjs';
+
+// This command changes only repository-local development-hook configuration. Release commands
+// do not import this module and do not consult the flag.
+try {
+  const [action = 'status', ...args] = process.argv.slice(2);
+  if (!['status', 'suspend', 'resume', 'check'].includes(action)
+    || (args.length && (args.length !== 2 || args[0] !== '--project'))) {
+    throw new Error('Usage: node scripts/development-maintenance.mjs status|suspend|resume [--project PATH]');
+  }
+  const status = maintenanceStatus(args[1] || process.cwd());
+  if (action === 'check') process.exit(status.suspended ? 0 : 1);
+  if (!status.project) throw new Error('Project must be inside a Git working tree');
+  if (action === 'status') {
+    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+  } else if ((action === 'suspend') === status.suspended) {
+    process.stdout.write(`${JSON.stringify({ ...status, changed: false }, null, 2)}\n`);
+  } else {
+    const receipt = {
+      schema: 1, id: randomUUID(), action, commonDir: status.commonDir,
+      suspended: action === 'suspend', timestamp: new Date().toISOString(),
+      scope: 'Brain development hooks only; release checks remain required',
+    };
+    const receiptsDir = path.join(status.commonDir, 'ruvnet-brain-maintenance-receipts');
+    fs.mkdirSync(receiptsDir, { mode: 0o700, recursive: true });
+    const receiptStat = fs.lstatSync(receiptsDir);
+    if (!receiptStat.isDirectory() || receiptStat.isSymbolicLink()
+      || (process.getuid && receiptStat.uid !== process.getuid())) throw new Error('Invalid maintenance receipt directory');
+    const receiptPath = path.join(receiptsDir, `${Date.now()}-${receipt.id}.json`);
+    // Record the decision before its side effect. A receipt alone never means suspension is active;
+    // status reads the actual state file, and a failed write exits nonzero.
+    fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    if (action === 'suspend') {
+      fs.writeFileSync(status.statePath, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    } else {
+      fs.unlinkSync(status.statePath);
+    }
+    process.stdout.write(`${JSON.stringify({ ...maintenanceStatus(status.project), changed: true, receiptPath }, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`development-maintenance: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/scripts/development-push-check.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Development pushes inspect unpublished commit patches for credentials. Release qualification
+// belongs to the single hosted producer, never a second checkout's Git hook.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function inspectPush(root, input) {
+  const checked = [];
+  for (const line of input.trim().split('\n').filter(Boolean)) {
+    const [, localSha, , remoteSha] = line.trim().split(/\s+/);
+    if (!/^[a-f0-9]{40}$/.test(localSha || '') || !/^[a-f0-9]{40}$/.test(remoteSha || '')) {
+      throw new Error('malformed Git push identity');
+    }
+    if (/^0+$/.test(localSha)) continue;
+    const range = /^0+$/.test(remoteSha) ? [localSha, '--not', '--remotes'] : [`${remoteSha}..${localSha}`];
+    const patch = execFileSync('git', ['log', '--format=', '--no-ext-diff', '-p', ...range],
+      { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 60_000 });
+    const additions = patch.split('\n').filter((row) => row.startsWith('+') && !row.startsWith('+++')).join('\n');
+    const matches = additions.match(/(?:sk-(?:proj|ant|or-v1)-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{30,})/g) || [];
+    if (matches.some((value) => !/your-key|abc123|xxxx+|deadbeef|example|placeholder|REDACTED/i.test(value))) {
+      throw new Error('credential-shaped value found in unpublished commit history');
+    }
+    checked.push(localSha);
+  }
+  return { ok: true, checked, scope: 'unpublished-commit-secret-scan' };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+    console.log(JSON.stringify(inspectPush(root, fs.readFileSync(0, 'utf8'))));
+  } catch (error) { console.error(`development push refused: ${error.message}`); process.exitCode = 1; }
+}

package/scripts/distill-project.mjs

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 /**
- * distill-project.mjs — the ONE genuinely offerable capability, made genuinely reversible.
+ * distill-project.mjs — snapshot-backed project distillation.
+ * Automatic restore is temporarily unavailable: the native CLI has no exact-snapshot restore,
+ * and the former raw-copy implementation was unsafe with live WAL writers. Backups are retained
+ * for supervised offline recovery; this wrapper no longer claims a verified automatic inverse.
  *
  * 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
@@ -31,13 +34,14 @@
  *   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.
+ * `--restore <snapshot>` now refuses before mutation; its WAL bytes-preservation test enforces that.
  */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { resolveRuflo, RUFLO_MISSING } from '../plugin/scripts/ruflo-bin.mjs';
+import { newestSnapshot, snapshotInventory, MTIME_GRACE_MS } from './snapshot-freshness.mjs';
 
 const HOME = os.homedir();
 // Issue #99: this was `process.env.RUFLO_BIN || path.join(HOME, '.npm-global/bin/ruflo')`, so every
@@ -96,50 +100,19 @@ function writeReceipt(rec) {
   } catch { return false; }
 }
 
-// Some filesystems truncate mtime to whole seconds (FAT32, some overlay/network mounts), so a file
-// written a moment after `sinceMs` was captured can still report an mtime slightly before it. This
-// grace window is tolerance for that truncation, not a loophole — it stays far smaller than the gap
-// between one run and the next.
-const MTIME_GRACE_MS = 1500;
-
-/**
- * The newest snapshot this project has, or null. With `sinceMs`, only a file whose mtime is no
- * older than that moment (minus the grace window) counts — so a stale snapshot left over from a
- * PRIOR run can never be mistaken for proof that THIS run's backup actually landed. `--restore`
- * calls this with no floor: it legitimately wants the newest snapshot ever, not the newest since a
- * particular run.
- */
-function newestSnapshot(sinceMs = 0) {
-  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 }))
-      .filter((x) => x.t >= sinceMs - MTIME_GRACE_MS)
-      .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();
+  const snap = arg('--restore', null) || newestSnapshot(BACKUP_DIR);
   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);
+  if (DRY) { say(`[dry-run] restore preview only; automatic WAL-safe restore is unavailable. Snapshot ${snap.replace(HOME, '~')}, destination ${DB.replace(HOME, '~')}.`); process.exit(0); }
+
+  // Ruflo exposes backup but no exact-snapshot restore CLI. Copying a live DB while WAL/SHM
+  // remain active can lose committed transactions. Keep every byte intact until a supported
+  // restore mechanism is available; a preview or backup file is not a verified recovery path.
+  die('WAL-safe restore is temporarily unavailable: no verified exact-snapshot Ruflo restore command exists. '
+    + 'No DB, WAL, SHM or backup bytes were changed. Retain the snapshot and coordinate an offline '
+    + 'SQLite recovery with all database users stopped; do not copy over a live store.');
 }
 
 // ── PRE-FLIGHT ─────────────────────────────────────────────────────────────────────────────────────
@@ -172,6 +145,9 @@ if (DRY) {
 // ── 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 backupStartedAt = Date.now();
+let priorSnapshots;
+try { priorSnapshots = snapshotInventory(BACKUP_DIR); }
+catch (error) { die(`REFUSING TO DISTILL — backup destination cannot be verified: ${error.message}`); }
 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`
@@ -181,7 +157,7 @@ if (!bk.ok) {
 // mistaken for proof that THIS backup call actually wrote something (issue: `ruflo memory backup`
 // exiting 0 without landing a new file — process killed post-commit, a --dir misconfiguration, a
 // ruflo regression — would otherwise be indistinguishable from a genuine fresh backup).
-const snapshot = newestSnapshot(backupStartedAt);
+const snapshot = newestSnapshot(BACKUP_DIR, backupStartedAt, MTIME_GRACE_MS, priorSnapshots);
 if (!snapshot) die('REFUSING TO DISTILL — `memory backup` reported success but no snapshot from this run is present, so the undo cannot be located.');
 say(`snapshot: ${snapshot.replace(HOME, '~')}`);
 
@@ -210,17 +186,18 @@ const outcome = {
   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}`,
+  restore: null,
+  restoreStatus: 'unavailable: retain snapshot for supervised offline recovery',
 };
 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}`);
+  say(`your store is unchanged or partially changed; retain ${snapshot} for supervised offline recovery. Automatic restore is unavailable.`);
   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.');
+if (delta === null) say('after   : counts could not be re-read, so the change is UNVERIFIED — retain the snapshot for offline recovery.');
 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}`);
+say(`restore : ${outcome.restoreStatus}`);