ruvnet-brain 4.3.9 → 4.3.10

package/bin/nightly-refresh.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Immutable scheduler target. Platform adapters execute this exact file with Node; this runner
+// alone owns the dynamic package-resolution command used to converge corpus and host surfaces.
+
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const runnerPath = path.resolve(fileURLToPath(import.meta.url));
+const registrationPath = String((process.argv[2] === '--registration' ? process.argv[3] : null) || process.env.RUVNET_NIGHTLY_REGISTRATION
+  || path.join(path.dirname(runnerPath), 'registration.json'));
+let registration;
+try {
+  if (!path.isAbsolute(registrationPath)) throw new Error('registration path is missing or not absolute');
+  registration = JSON.parse(fs.readFileSync(registrationPath, 'utf8'));
+  const runnerSha256 = crypto.createHash('sha256').update(fs.readFileSync(runnerPath)).digest('hex');
+  if (registration.schemaVersion !== 2 || registration.kind !== 'ruvnet-brain-nightly-scheduler'
+    || (registration.identity !== 'com.ruvnet.brain-update'
+      && !/^com\.ruvnet\.brain-update\.proof-[A-Za-z0-9._-]+$/.test(registration.identity || ''))
+    || path.resolve(registration.runnerPath || '') !== runnerPath
+    || registration.runnerSha256 !== runnerSha256
+    || path.resolve(registration.nodePath || '') !== path.resolve(process.execPath)
+    || !Array.isArray(registration.argv) || registration.argv.length !== 0
+    || !registration.packageTarget || typeof registration.packageTarget.spec !== 'string') {
+    throw new Error('registration does not bind this exact runner and Node executable');
+  }
+  if (registration.packageTarget.sha256 !== null) {
+    if (!path.isAbsolute(registration.packageTarget.spec)
+      || !/^[a-f0-9]{64}$/.test(registration.packageTarget.sha256)
+      || crypto.createHash('sha256').update(fs.readFileSync(registration.packageTarget.spec)).digest('hex')
+        !== registration.packageTarget.sha256) throw new Error('registered package target digest mismatch');
+  } else if (registration.packageTarget.spec !== 'ruvnet-brain@latest') {
+    throw new Error('unhashed package target is not the production latest channel');
+  }
+  const proof = /^com\.ruvnet\.brain-update\.proof-[A-Za-z0-9._-]+$/.test(registration.identity);
+  if (proof) {
+    const bundleStat = fs.lstatSync(registration.bundleTarget?.spec || '');
+    if (!registration.bundleTarget || !path.isAbsolute(registration.bundleTarget.spec)
+      || !registration.bundleTarget.spec.endsWith('.zip')
+      || !bundleStat.isFile() || bundleStat.isSymbolicLink()
+      || !/^[a-f0-9]{64}$/.test(registration.bundleTarget.sha256)
+      || crypto.createHash('sha256').update(fs.readFileSync(registration.bundleTarget.spec)).digest('hex')
+        !== registration.bundleTarget.sha256) throw new Error('registered bundle target digest mismatch');
+  } else if (registration.bundleTarget !== null && registration.bundleTarget !== undefined) {
+    throw new Error('production nightly registration cannot pin a local bundle');
+  }
+} catch (error) {
+  console.error(`RuvNet Brain nightly refresh registration is invalid: ${error.message}`);
+  process.exit(1);
+}
+
+const allowedEnvironment = ['PATH', 'HOME', 'USERPROFILE', 'RUVNET_BRAIN_HOME', 'RUVNET_BRAIN_KB', 'npm_config_cache', 'NO_COLOR', 'SystemRoot', 'SYSTEMROOT', 'ComSpec', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP'];
+if (registration.environment !== undefined && (!registration.environment || Array.isArray(registration.environment)
+  || Object.entries(registration.environment).some(([key, value]) => !allowedEnvironment.includes(key) || typeof value !== 'string'))) {
+  console.error('Invalid registered nightly environment'); process.exit(1);
+}
+Object.assign(process.env, registration.environment || {});
+
+const npxName = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+const adjacent = path.join(path.dirname(process.execPath), npxName);
+const npx = fs.existsSync(adjacent) ? adjacent : npxName;
+const argv = ['--yes', registration.packageTarget.spec, '--update', '--no-nightly-prompt'];
+let executable = npx;
+let launchArgs = argv;
+if (process.platform === 'win32') {
+  // This content-addressed runner is copied alone: keep its dependency closure standalone.
+  // Like rufloInvocation, execute the managed package's declared JS entry, never a .cmd shell.
+  try {
+    const shim = fs.existsSync(adjacent) ? adjacent : String(process.env.PATH || '')
+      .split(path.delimiter).filter(Boolean).map(dir => path.join(dir, npxName))
+      .find(candidate => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+    if (!shim) throw new Error('managed npm npx shim is missing');
+    const packageRoot = fs.realpathSync(path.join(path.dirname(fs.realpathSync(shim)), 'node_modules', 'npm'));
+    const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    const declared = manifest.bin?.npx;
+    if (manifest.name !== 'npm' || typeof declared !== 'string' || !declared
+      || path.isAbsolute(declared) || path.win32.isAbsolute(declared) || declared.split(/[\\/]/).includes('..')) {
+      throw new Error('managed npm package has no safe declared npx entry');
+    }
+    const entry = fs.realpathSync(path.resolve(packageRoot, declared));
+    const relative = path.relative(packageRoot, entry);
+    if (!relative || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || !fs.statSync(entry).isFile()) {
+      throw new Error('managed npm npx entry escapes its package');
+    }
+    executable = process.execPath;
+    launchArgs = [entry, ...argv];
+  } catch (error) {
+    console.error(`RuvNet Brain nightly refresh could not resolve managed npm: ${error.message}`);
+    process.exit(1);
+  }
+}
+const allowed = ['PATH', 'HOME', 'USERPROFILE', 'RUVNET_BRAIN_HOME', 'RUVNET_BRAIN_KB',
+  'npm_config_cache', 'NO_COLOR', 'SystemRoot', 'SYSTEMROOT', 'ComSpec', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP'];
+const childEnv = Object.fromEntries(allowed.filter((key) => process.env[key] !== undefined)
+  .map((key) => [key, process.env[key]]));
+const result = spawnSync(executable, launchArgs, {
+  stdio: 'inherit',
+  shell: false,
+  env: { ...childEnv, RUVNET_NIGHTLY: '1',
+    RUVNET_NIGHTLY_REGISTRATION: registrationPath,
+    RUVNET_NIGHTLY_IDENTITY: registration.identity,
+    RUVNET_NIGHTLY_NODE_PATH: registration.nodePath,
+    RUVNET_NIGHTLY_RUNNER_PATH: registration.runnerPath,
+    RUVNET_NIGHTLY_RUNNER_SHA256: registration.runnerSha256,
+  },
+});
+
+if (result.error) {
+  console.error(`RuvNet Brain nightly refresh could not start: ${result.error.message}`);
+  process.exitCode = 1;
+} else {
+  process.exitCode = result.status === null ? 1 : result.status;
+}

package/kb/brain-profile.mjs

@@ -42,34 +42,92 @@ function familyEntries(dir, store) {
     entry === `${store}-primer.md` || entry === store || entry.startsWith(`${store}.`));
 }
 
-function filterCapabilityCards(dir) {
+// SOURCE is the existing update-ownership policy; PRIVATE-STORES is the existing
+// case-insensitive publication fence. Neither discovery nor a filename prefix grants ownership.
+function profileOwnership(dir) {
+  const read = (name) => {
+    const file = path.join(dir, name);
+    if (!fs.lstatSync(file).isFile()) throw new Error(`profile ownership requires regular ${name}`);
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  };
+  const source = read('SOURCE.json');
+  const fence = read('PRIVATE-STORES.json');
+  if (!Array.isArray(fence.privateStores) || fence.privateStores.some((s) => typeof s !== 'string' || !s)) {
+    throw new Error('invalid PRIVATE-STORES ownership policy');
+  }
+  const entries = Array.isArray(source.stores)
+    ? source.stores.map((s) => [s?.kbName, s])
+    : source.stores && typeof source.stores === 'object'
+      ? Object.entries(source.stores) : null;
+  if (!entries) throw new Error('invalid SOURCE ownership policy');
+  const privateNames = new Set(fence.privateStores.map((s) => s.toLowerCase()));
+  const managed = new Set();
+  const seen = new Set();
+  for (const [name, value] of entries) {
+    if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/i.test(name)
+      || !value || typeof value !== 'object' || Array.isArray(value)
+      || (value.kbName != null && value.kbName !== name)
+      || (value.updateManaged != null && typeof value.updateManaged !== 'boolean')
+      || seen.has(name.toLowerCase())) throw new Error('invalid SOURCE store ownership');
+    seen.add(name.toLowerCase());
+    if (value.updateManaged !== false && !privateNames.has(name.toLowerCase())) managed.add(name);
+  }
+  return { managed, read };
+}
+
+// Only published artifact spellings, never arbitrary store.* siblings or directories.
+function managedEntries(dir, store) {
+  const names = new Set([`${store}-primer.md`, ...[
+    '.rvf', '.big.rvf', '.idmap.json', '.rvf.idmap.json', '.rvf.embed.json',
+    '.big.rvf.idmap.json', '.big.rvf.embed.json', '.passages.jsonl',
+    '.big.passages.jsonl', '.meta.json', '.big.meta.json', '.symbols.json',
+  ].map((suffix) => `${store}${suffix}`)]);
+  return fs.readdirSync(dir).filter((entry) => names.has(entry));
+}
+
+function requireRegular(dir, entries) {
+  for (const entry of entries) {
+    if (!fs.lstatSync(path.join(dir, entry)).isFile()) {
+      throw new Error(`profile requires regular artifact, not directory or symbolic link: ${entry}`);
+    }
+  }
+}
+
+function cardParts(text) {
+  return text.split(/(?=^## )/m);
+}
+
+function cardName(part) {
+  return part.match(/^## ([^\n]+)\s*$/m)?.[1]?.trim();
+}
+
+function filterCapabilityCards(dir, managed, { validateOnly = false } = {}) {
   const file = path.join(dir, 'capability-cards.md');
   if (!fs.existsSync(file)) return;
   const backup = path.join(dir, 'capability-cards.complete.md');
   const current = fs.readFileSync(file, 'utf8');
-  const cardCount = (current.match(/^## /gm) || []).length;
-  if (!fs.existsSync(backup) || cardCount > 1) fs.copyFileSync(file, backup);
-  const full = fs.readFileSync(backup, 'utf8');
-  const firstCard = full.search(/^## /m);
-  const start = full.search(/^## ruvector\s*$/m);
-  if (firstCard < 0 || start < 0) throw new Error('could not isolate the RuVector capability card');
-  const rest = full.slice(start);
-  const next = rest.slice(1).search(/^## /m);
-  const card = next < 0 ? rest : rest.slice(0, next + 1);
-  fs.writeFileSync(file, `${full.slice(0, firstCard)}${card.trimEnd()}\n`);
+  if (!/^## ruvector\s*$/m.test(current)) throw new Error('could not isolate the RuVector capability card');
+  const keep = (part) => !managed.has(cardName(part)) || cardName(part) === PROFILE_RUVECTOR;
+  if (validateOnly) return;
+  if (!fs.existsSync(backup) || cardParts(current).some((part) => !keep(part))) fs.copyFileSync(file, backup);
+  fs.writeFileSync(file, cardParts(current).filter(keep).join(''));
 }
 
 function restoreCapabilityCards(dir) {
   const backup = path.join(dir, 'capability-cards.complete.md');
-  if (fs.existsSync(backup)) fs.copyFileSync(backup, path.join(dir, 'capability-cards.md'));
+  if (fs.existsSync(backup)) {
+    const { managed } = profileOwnership(dir);
+    requireRegular(dir, ['capability-cards.complete.md', 'capability-cards.md']);
+    mergeCapabilityCards(dir, fs.readFileSync(backup, 'utf8'), managed);
+  }
 }
 
-function filterGenerationLedger(dir, allowed) {
-  const file = path.join(dir, 'RVF-GENERATIONS.json');
-  if (!fs.existsSync(file)) return;
-  const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
-  doc.stores = Object.fromEntries(Object.entries(doc.stores || {}).filter(([name]) => allowed.has(name)));
-  fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
+function mergeCapabilityCards(dir, incoming, managed) {
+  const file = path.join(dir, 'capability-cards.md');
+  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const preserved = cardParts(current).filter((part) => cardName(part) && !managed.has(cardName(part)));
+  const next = cardParts(incoming).filter((part) => !cardName(part) || managed.has(cardName(part)));
+  fs.writeFileSync(file, [...next, ...preserved].join(''));
 }
 
 export function applyBrainProfile(dir, profile) {
@@ -80,21 +138,33 @@ export function applyBrainProfile(dir, profile) {
   }
 
   const allowed = new Set([PROFILE_RUVECTOR]);
+  const ownership = profileOwnership(dir);
+  const ledger = ownership.read('RVF-GENERATIONS.json');
+  if (!ledger.stores || typeof ledger.stores !== 'object' || Array.isArray(ledger.stores)) {
+    throw new Error('invalid RVF-GENERATIONS ownership metadata');
+  }
+  const plan = discoverStoreFamilies(dir)
+    .filter((store) => !allowed.has(store) && ownership.managed.has(store))
+    .map((store) => ({ store, entries: managedEntries(dir, store) }));
+  for (const { entries } of plan) requireRegular(dir, entries);
+  requireRegular(dir, ['capability-cards.md', 'capability-cards.complete.md']
+    .filter((name) => fs.readdirSync(dir).includes(name)));
+  filterCapabilityCards(dir, ownership.managed, { validateOnly: true });
   const removed = [];
   const removedStores = [];
   let bytesFreed = 0;
-  for (const store of discoverStoreFamilies(dir)) {
-    if (allowed.has(store)) continue;
+  for (const { store, entries } of plan) {
     removedStores.push(store);
-    for (const entry of familyEntries(dir, store)) {
+    for (const entry of entries) {
       const target = path.join(dir, entry);
       try { bytesFreed += fs.statSync(target).size; } catch { /* report only measured bytes */ }
-      fs.rmSync(target, { recursive: true, force: true });
+      fs.unlinkSync(target);
       removed.push(entry);
     }
   }
-  filterCapabilityCards(dir);
-  filterGenerationLedger(dir, allowed);
+  filterCapabilityCards(dir, ownership.managed);
+  for (const store of removedStores) delete ledger.stores[store];
+  fs.writeFileSync(path.join(dir, 'RVF-GENERATIONS.json'), `${JSON.stringify(ledger, null, 2)}\n`);
   return { profile, removed, removedStores, bytesFreed, stores: discoverStoreFamilies(dir) };
 }
 
@@ -102,23 +172,39 @@ export function restoreCompleteProfile(targetDir, sourceDir) {
   if (!discoverStoreFamilies(sourceDir).includes(PROFILE_RUVECTOR)) {
     throw new Error(`complete bundle source is unavailable at ${sourceDir}`);
   }
-  fs.mkdirSync(targetDir, { recursive: true });
-  const stores = discoverStoreFamilies(sourceDir);
+  const sourceOwnership = profileOwnership(sourceDir);
+  const targetOwnership = profileOwnership(targetDir);
+  const sourceLedger = sourceOwnership.read('RVF-GENERATIONS.json');
+  const targetLedger = targetOwnership.read('RVF-GENERATIONS.json');
+  for (const ledger of [sourceLedger, targetLedger]) {
+    if (!ledger.stores || typeof ledger.stores !== 'object' || Array.isArray(ledger.stores)) {
+      throw new Error('invalid RVF-GENERATIONS ownership metadata');
+    }
+  }
+  const stores = discoverStoreFamilies(sourceDir).filter((store) => sourceOwnership.managed.has(store));
   for (const store of stores) {
-    for (const entry of familyEntries(sourceDir, store)) {
+    if (!targetOwnership.managed.has(store)) throw new Error(`private or unknown restoration ownership: ${store}`);
+    requireRegular(sourceDir, managedEntries(sourceDir, store));
+    requireRegular(targetDir, managedEntries(targetDir, store));
+  }
+  requireRegular(sourceDir, ['capability-cards.md']);
+  requireRegular(targetDir, ['capability-cards.md', 'capability-cards.complete.md']
+    .filter((name) => fs.readdirSync(targetDir).includes(name)));
+  for (const store of stores) {
+    for (const entry of managedEntries(sourceDir, store)) {
       fs.cpSync(path.join(sourceDir, entry), path.join(targetDir, entry), {
         recursive: true,
         force: true,
       });
     }
+    if (sourceLedger.stores[store]) targetLedger.stores[store] = sourceLedger.stores[store];
   }
-  for (const entry of ['capability-cards.md', 'RVF-GENERATIONS.json']) {
-    const source = path.join(sourceDir, entry);
-    if (fs.existsSync(source)) fs.copyFileSync(source, path.join(targetDir, entry));
-  }
+  targetLedger.stores = Object.fromEntries(Object.entries(targetLedger.stores).sort(([a], [b]) => a.localeCompare(b)));
+  fs.writeFileSync(path.join(targetDir, 'RVF-GENERATIONS.json'), `${JSON.stringify(targetLedger, null, 2)}\n`);
   const cards = path.join(sourceDir, 'capability-cards.md');
   if (fs.existsSync(cards)) {
-    fs.copyFileSync(cards, path.join(targetDir, 'capability-cards.complete.md'));
+    mergeCapabilityCards(targetDir, fs.readFileSync(cards, 'utf8'), new Set(stores));
+    fs.copyFileSync(path.join(targetDir, 'capability-cards.md'), path.join(targetDir, 'capability-cards.complete.md'));
   }
   return { profile: PROFILE_COMPLETE, stores: discoverStoreFamilies(targetDir) };
 }

package/kb/lifecycle-evidence-retention.mjs

@@ -0,0 +1,237 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const TERMINAL_REFRESH = new Set(['SUCCEEDED', 'FAILED', 'ABANDONED']);
+const TERMINAL_TRANSACTION = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK']);
+const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+const PHASE_FILE = /^\d{3}-[A-Z_]+\.json$/;
+const QUARANTINE = /^\.prune-[A-Za-z0-9._-]+-[a-f0-9]{16}$/;
+
+export const LIFECYCLE_EVIDENCE_RETENTION_POLICY = Object.freeze({
+  schemaVersion: 1,
+  policyId: 'lifecycle-evidence-v1',
+  maxRefreshReceipts: 32,
+  maxTransactionDirectories: 16,
+  maxEvidenceBytes: 16 * 1024 * 1024,
+});
+
+function rootsFor({ brainHome, kbDir }) {
+  const home = path.resolve(brainHome || path.dirname(path.resolve(kbDir || '')));
+  const live = path.resolve(kbDir || path.join(home, 'kb'));
+  return { refresh: path.join(home, 'refresh-runs'),
+    transactions: path.join(path.dirname(live), `.${path.basename(live)}.update-transactions`) };
+}
+
+function regularJson(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('not a trusted regular file');
+  return { value: JSON.parse(fs.readFileSync(file, 'utf8')), bytes: stat.size };
+}
+
+function treeBytes(root) {
+  const stat = fs.lstatSync(root);
+  if (stat.isSymbolicLink()) throw new Error('symbolic link is not trusted evidence');
+  if (stat.isFile()) return stat.size;
+  if (!stat.isDirectory()) throw new Error('special file is not trusted evidence');
+  let bytes = 0;
+  for (const name of fs.readdirSync(root)) bytes += treeBytes(path.join(root, name));
+  return bytes;
+}
+
+function stamp(value, label) {
+  const parsed = Date.parse(value || '');
+  if (!Number.isFinite(parsed)) throw new Error(`${label} has no valid semantic timestamp`);
+  return parsed;
+}
+
+function scanRefresh(root, unsafe) {
+  if (!fs.existsSync(root)) return [];
+  const rows = [];
+  for (const name of fs.readdirSync(root).sort()) {
+    const file = path.join(root, name);
+    if (QUARANTINE.test(name)) {
+      unsafe.push({ path: file, reason: 'recognized pruning quarantine remains' });
+      continue;
+    }
+    try {
+      if (!name.endsWith('.json')) throw new Error('unexpected refresh evidence entry');
+      const { value: receipt, bytes } = regularJson(file);
+      const runId = name.slice(0, -5);
+      if (!SAFE_ID.test(runId) || receipt?.schemaVersion !== 3 || receipt?.kind !== 'ruvnet-brain-refresh-run'
+        || receipt.runId !== runId || !['RUNNING', 'SETTLING', ...TERMINAL_REFRESH].includes(receipt.status)) {
+        throw new Error('malformed refresh receipt identity or state');
+      }
+      rows.push({ kind: 'refresh', id: runId, path: file, bytes,
+        timestamp: stamp(receipt.finishedAt || receipt.startedAt, `refresh ${runId}`), receipt });
+    } catch (error) { unsafe.push({ path: file, reason: error.message }); }
+  }
+  return rows;
+}
+
+function scanTransactions(root, unsafe) {
+  if (!fs.existsSync(root)) return [];
+  const rows = [];
+  for (const name of fs.readdirSync(root).sort()) {
+    const dir = path.join(root, name);
+    if (QUARANTINE.test(name)) {
+      unsafe.push({ path: dir, reason: 'recognized pruning quarantine remains' });
+      continue;
+    }
+    try {
+      const stat = fs.lstatSync(dir);
+      if (!SAFE_ID.test(name) || !stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error('malformed transaction evidence entry');
+      }
+      const names = fs.readdirSync(dir).sort();
+      if (!names.length || names.some((file) => !PHASE_FILE.test(file))) throw new Error('transaction phase inventory is malformed');
+      const phases = names.map((file) => regularJson(path.join(dir, file)).value);
+      const latest = phases.at(-1);
+      if (latest?.kind !== 'ruvnet-brain-storage-transaction-phase' || latest.transactionId !== name
+        || latest.sequence !== names.length || typeof latest.state !== 'string') {
+        throw new Error('transaction phase identity is malformed');
+      }
+      rows.push({ kind: 'transaction', id: name, path: dir, bytes: treeBytes(dir),
+        timestamp: stamp(latest.recordedAt, `transaction ${name}`), latest });
+    } catch (error) { unsafe.push({ path: dir, reason: error.message }); }
+  }
+  return rows;
+}
+
+function transactionReferences(value, output = []) {
+  if (!value || typeof value !== 'object') return output;
+  if (Object.hasOwn(value, 'transactionReceipts') && value.transactionReceipts !== null) {
+    output.push(value.transactionReceipts);
+  }
+  for (const nested of Array.isArray(value) ? value : Object.values(value)) transactionReferences(nested, output);
+  return output;
+}
+
+function newest(rows, predicate) {
+  return rows.filter(predicate).sort((a, b) => b.timestamp - a.timestamp || b.id.localeCompare(a.id))[0] || null;
+}
+
+function trustedEvidenceRoot(root, unsafe) {
+  try {
+    for (const entry of [path.dirname(root), root]) {
+      const stat = fs.lstatSync(entry);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('evidence root is not a trusted directory (symbolic or special entry)');
+    }
+    return true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') unsafe.push({ path: root, reason: error.message });
+    return false;
+  }
+}
+
+function snapshot(options) {
+  const roots = rootsFor(options);
+  const unsafe = [];
+  const refresh = trustedEvidenceRoot(roots.refresh, unsafe) ? scanRefresh(roots.refresh, unsafe) : [];
+  const transactions = trustedEvidenceRoot(roots.transactions, unsafe) ? scanTransactions(roots.transactions, unsafe) : [];
+  const preserveRefresh = new Set((options.preserveRefreshRunIds || []).map(String));
+  const preserveTransactions = new Set((options.preserveTransactionPaths || []).map((entry) => path.resolve(entry)));
+  const protectedRefresh = new Map();
+  const protectRefresh = (row, reason) => { if (row) protectedRefresh.set(row.path, reason); };
+  for (const row of refresh) {
+    if (['RUNNING', 'SETTLING'].includes(row.receipt.status)) protectRefresh(row, `active ${row.receipt.status}`);
+    if (preserveRefresh.has(row.id)) protectRefresh(row, 'explicitly preserved refresh run');
+  }
+  protectRefresh(newest(refresh, (row) => row.receipt.action === 'nightly'), 'newest nightly receipt');
+  protectRefresh(newest(refresh, (row) => row.receipt.action === 'update'), 'newest update receipt');
+  protectRefresh(newest(refresh, (row) => row.receipt.status === 'FAILED'), 'newest failed receipt');
+  protectRefresh(newest(refresh, (row) => row.receipt.status === 'ABANDONED'), 'newest abandoned receipt');
+
+  const retainedTransactionPaths = new Set();
+  for (const row of refresh) {
+    if (!protectedRefresh.has(row.path)) continue;
+    for (const reference of transactionReferences(row.receipt)) {
+      const resolved = path.resolve(String(reference || ''));
+      const relative = path.relative(roots.transactions, resolved);
+      if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || relative.includes(path.sep)) {
+        unsafe.push({ path: row.path, reason: `forged external transaction reference: ${String(reference)}` });
+      } else retainedTransactionPaths.add(resolved);
+    }
+  }
+  const protectedTransactions = new Map();
+  for (const row of transactions) {
+    if (!TERMINAL_TRANSACTION.has(row.latest.state)) protectedTransactions.set(row.path, `nonterminal ${row.latest.state}`);
+    if (preserveTransactions.has(row.path)) protectedTransactions.set(row.path, 'explicitly preserved transaction');
+    if (retainedTransactionPaths.has(row.path)) protectedTransactions.set(row.path, 'referenced by retained refresh receipt');
+  }
+  const bytes = [...refresh, ...transactions].reduce((sum, row) => sum + row.bytes, 0)
+    + unsafe.filter(({ reason }) => /quarantine remains/.test(reason)).reduce((sum, { path: entry }) => {
+      try { return sum + treeBytes(entry); } catch { return sum; }
+    }, 0);
+  return { roots, unsafe, refresh, transactions, bytes, protectedRefresh, protectedTransactions };
+}
+
+function counts(state) {
+  return { refreshReceipts: state.refresh.length, transactionDirectories: state.transactions.length, bytes: state.bytes };
+}
+
+function isWithin(state, policy) {
+  return state.unsafe.length === 0 && state.refresh.length <= policy.maxRefreshReceipts
+    && state.transactions.length <= policy.maxTransactionDirectories && state.bytes <= policy.maxEvidenceBytes;
+}
+
+export function assessLifecycleEvidence(options = {}) {
+  const policy = options.policy || LIFECYCLE_EVIDENCE_RETENTION_POLICY;
+  const state = snapshot(options);
+  return { schemaVersion: 1, kind: 'ruvnet-brain-lifecycle-evidence-retention', policy,
+    observedAt: (options.now || (() => new Date().toISOString()))(), before: counts(state),
+    protected: {
+      refresh: [...state.protectedRefresh].map(([entryPath, reason]) => ({ path: entryPath, reason })),
+      transactions: [...state.protectedTransactions].map(([entryPath, reason]) => ({ path: entryPath, reason })),
+    },
+    removable: {
+      refresh: state.refresh.filter((row) => TERMINAL_REFRESH.has(row.receipt.status) && !state.protectedRefresh.has(row.path))
+        .sort((a, b) => a.timestamp - b.timestamp).map(({ path: entryPath }) => entryPath),
+      transactions: state.transactions.filter((row) => TERMINAL_TRANSACTION.has(row.latest.state)
+        && !state.protectedTransactions.has(row.path)).sort((a, b) => a.timestamp - b.timestamp)
+        .map(({ path: entryPath }) => entryPath),
+    },
+    removed: { refresh: [], transactions: [] }, after: counts(state), unsafe: state.unsafe,
+    withinBudget: isWithin(state, policy) };
+}
+
+function quarantineAndRemove(entry, root, removeEntry, afterQuarantine) {
+  const name = path.basename(entry);
+  const resolved = path.resolve(entry);
+  if (path.dirname(resolved) !== path.resolve(root) || !SAFE_ID.test(name.replace(/\.json$/, ''))) {
+    throw new Error(`refusing unsafe lifecycle evidence removal: ${entry}`);
+  }
+  const quarantine = path.join(root, `.prune-${name.replace(/\.json$/, '')}-${crypto.randomBytes(8).toString('hex')}`);
+  fs.renameSync(resolved, quarantine);
+  afterQuarantine?.({ entry: resolved, quarantine });
+  removeEntry(quarantine);
+}
+
+export function pruneLifecycleEvidence(options = {}) {
+  const policy = options.policy || LIFECYCLE_EVIDENCE_RETENTION_POLICY;
+  const removeEntry = options.removeEntry || ((entry) => fs.rmSync(entry, { recursive: true, force: true }));
+  // A prior invocation's quarantine name is not proof of ownership of its current
+  // bytes. Preserve it as unsafe, measured evidence; only this invocation may remove
+  // the exact entry it just quarantined. Recovery must not guess away private data.
+  const initial = assessLifecycleEvidence({ ...options, policy });
+  const removed = { refresh: [], transactions: [] };
+  for (;;) {
+    const state = snapshot(options);
+    if (isWithin(state, policy)) break;
+    if (state.unsafe.length) break;
+    const refreshCandidates = state.refresh.filter((row) => TERMINAL_REFRESH.has(row.receipt.status)
+      && !state.protectedRefresh.has(row.path)).sort((a, b) => a.timestamp - b.timestamp);
+    const transactionCandidates = state.transactions.filter((row) => TERMINAL_TRANSACTION.has(row.latest.state)
+      && !state.protectedTransactions.has(row.path)).sort((a, b) => a.timestamp - b.timestamp);
+    let candidate = state.refresh.length > policy.maxRefreshReceipts ? refreshCandidates[0]
+      : state.transactions.length > policy.maxTransactionDirectories ? transactionCandidates[0]
+        : [...refreshCandidates, ...transactionCandidates].sort((a, b) => a.timestamp - b.timestamp)[0];
+    if (!candidate) break;
+    const root = candidate.kind === 'refresh' ? state.roots.refresh : state.roots.transactions;
+    quarantineAndRemove(candidate.path, root, removeEntry, options.afterQuarantine);
+    removed[candidate.kind === 'refresh' ? 'refresh' : 'transactions'].push(candidate.path);
+  }
+  const final = assessLifecycleEvidence({ ...options, policy });
+  return { ...final, before: initial.before, removed,
+    after: final.after, withinBudget: final.withinBudget };
+}