ruvnet-brain 4.3.8 → 4.3.10

package/scripts/release-qualification.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { digest } from './coverage-integrity.mjs';
+import { sourceIdentity } from './qa-contract.mjs';
+import { RELEASE_REQUIREMENTS } from './release-qualification-contract.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PLATFORM = { linux: 'linux', darwin: 'macos', win32: 'windows' }[process.platform];
+
+export function qualificationPlan(suite = 'source') {
+  const requirements = RELEASE_REQUIREMENTS[suite];
+  if (!requirements?.length) throw new Error('unknown qualification suite');
+  const files = requirements.flatMap((entry) => entry.files);
+  if (new Set(files).size !== files.length || files.some((file) => !file.startsWith('tests/')
+    || !file.endsWith('.test.mjs') || file.includes('..'))) throw new Error('invalid qualification inventory');
+  return { requirements, files, contractSha256: digest(requirements) };
+}
+
+export function assessTestReport(report, files, root = ROOT, platform = PLATFORM) {
+  if (!['linux', 'macos', 'windows'].includes(platform)) throw new Error('invalid test report platform');
+  const paths = platform === 'windows' ? path.win32 : path.posix;
+  if (typeof root !== 'string' || !paths.isAbsolute(root)) throw new Error('test report checkout root must be absolute');
+  const results = report?.testResults;
+  if (!Array.isArray(results) || results.length !== files.length) throw new Error('test report file inventory differs');
+  const expected = new Set(files.map((file) => paths.resolve(root, file)));
+  if (results.some(file => typeof file.name !== 'string' || !paths.isAbsolute(file.name))) throw new Error('test report file inventory requires absolute names');
+  const names = results.map((file) => paths.resolve(file.name));
+  if (new Set(names).size !== files.length || names.some((name) => !expected.has(name))) {
+    throw new Error('test report contains missing, duplicate, or unexpected files');
+  }
+  const cases = results.flatMap((file) => file.assertionResults || []);
+  if (!cases.length || results.some((file) => file.status !== 'passed' || !file.assertionResults?.length)
+    || cases.some((test) => test.status !== 'passed') || report.success !== true
+    || report.numFailedTests !== 0 || report.numFailedTestSuites !== 0
+    || report.numPendingTests !== 0 || (report.numTodoTests || 0) !== 0
+    || report.numTotalTests !== cases.length || report.numPassedTests !== cases.length) {
+    throw new Error('reviewed release cases did not all execute and pass');
+  }
+  return { total: cases.length, passed: cases.length, failed: 0, skipped: 0 };
+}
+
+export function validateQualificationReceipt(report, { suite, platform, sourceSha }) {
+  const plan = qualificationPlan(suite);
+  const { receiptSha256, ...payload } = report || {};
+  if (report?.schemaVersion !== 1 || report.kind !== 'ruvnet-brain-release-qualification'
+    || report.suite !== suite || report.platform !== platform || report.status !== 'PASS'
+    || digest(payload) !== receiptSha256 || report.contractSha256 !== plan.contractSha256
+    || digest(report.files) !== digest(plan.files)
+    || digest(report.requirements) !== digest(plan.requirements.map(row => row.id))) {
+    throw new Error('qualification receipt identity, digest, or reviewed contract differs');
+  }
+  if (!/^[a-f0-9]{40}$/.test(String(sourceSha)) || report.source?.sha !== sourceSha
+    || report.sourceAfter?.sha !== sourceSha || report.source.dirty !== false || report.sourceAfter.dirty !== false
+    || !/^[a-f0-9]{64}$/.test(report.source.digest || '') || report.source.digest !== report.sourceAfter.digest
+    || report.sourceStable !== true) throw new Error('qualification source is not clean and unchanged');
+  if (!Array.isArray(report.results) || !report.results.length
+    || report.results.some(row => row.status !== 'PASS' || row.exitCode !== 0)) {
+    throw new Error('qualification command did not complete successfully');
+  }
+  if (typeof report.checkoutRoot !== 'string' || !report.checkoutRoot) throw new Error('qualification checkout root is missing');
+  const tests = assessTestReport(report.testReport, plan.files, report.checkoutRoot, platform);
+  if (digest(tests) !== digest(report.tests)) throw new Error('qualification test summary differs from executed cases');
+  return tests;
+}
+
+export function runQualification({ suite = 'source', platform = PLATFORM, report: output, root = ROOT } = {}) {
+  if (platform !== PLATFORM) throw new Error(`cannot produce ${platform} evidence on ${PLATFORM}`);
+  if (!output || fs.existsSync(output)) throw new Error('a new --report path is required');
+  const plan = qualificationPlan(suite);
+  for (const file of plan.files) if (!fs.statSync(path.resolve(root, file)).isFile()) throw new Error(`missing test ${file}`);
+  const source = sourceIdentity(root);
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'release-qualification-'));
+  const results = [];
+  let testReport = null;
+  let tests = { total: 0, passed: 0, failed: 0, skipped: 0 };
+  const execute = (name, args) => {
+    const run = spawnSync(process.execPath, ['scripts/ci/step-watchdog.mjs', '--name', name,
+      '--timeout-ms', '900000', '--receipt-dir', temp, '--', process.execPath, ...args],
+    { cwd: root, env: { ...process.env, ...(suite === 'integration' ? { RUVNET_REQUIRE_CODEX_DISCOVERY: '1' } : {}) },
+      stdio: 'inherit' });
+    const ok = !run.error && run.status === 0;
+    results.push({ name, status: ok ? 'PASS' : 'FAIL', exitCode: run.status });
+    if (!ok) throw new Error(`${name} failed`);
+  };
+  let failure = null;
+  try {
+    if (suite === 'source') {
+      execute('release-version', ['scripts/sync-version.mjs', '--check']);
+      execute('release-source-identity', ['scripts/convergence-manifest.mjs']);
+      execute('automatic-hook-retirement', ['scripts/hook-retirement-check.mjs']);
+    }
+    const testPath = path.join(temp, 'tests.json');
+    execute(`release-${suite}-${platform}`, ['node_modules/vitest/vitest.mjs', 'run', ...plan.files,
+      '--reporter=json', '--outputFile', testPath, '--maxWorkers=1']);
+    testReport = JSON.parse(fs.readFileSync(testPath, 'utf8'));
+    tests = assessTestReport(testReport, plan.files, root);
+  } catch (error) {
+    failure = error.message;
+    const testPath = path.join(temp, 'tests.json');
+    if (fs.existsSync(testPath)) {
+      try {
+        testReport = JSON.parse(fs.readFileSync(testPath, 'utf8'));
+        tests = { total: testReport.numTotalTests || 0, passed: testReport.numPassedTests || 0,
+          failed: testReport.numFailedTests || 0,
+          skipped: (testReport.numPendingTests || 0) + (testReport.numTodoTests || 0) };
+      } catch { /* failed report remains a failure */ }
+    }
+  }
+  const sourceAfter = sourceIdentity(root);
+  const sourceStable = source.digest === sourceAfter.digest;
+  const receipt = { schemaVersion: 1, kind: 'ruvnet-brain-release-qualification', suite, platform, checkoutRoot: path.resolve(root),
+    source, sourceAfter, sourceStable, status: !failure && sourceStable ? 'PASS' : 'FAIL',
+    requirements: plan.requirements.map((entry) => entry.id), contractSha256: plan.contractSha256,
+    files: plan.files, tests, testReport, results, failure, observedAt: new Date().toISOString() };
+  receipt.receiptSha256 = digest(receipt);
+  fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+  fs.writeFileSync(output, JSON.stringify(receipt, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  fs.rmSync(temp, { recursive: true, force: true });
+  return receipt;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const value = (flag, fallback) => { const i = args.indexOf(flag); return i < 0 ? fallback : args[i + 1]; };
+  try {
+    const receipt = runQualification({ suite: value('--suite', 'source'), platform: value('--platform', PLATFORM),
+      report: value('--report') });
+    console.log(JSON.stringify({ status: receipt.status, tests: receipt.tests, receiptSha256: receipt.receiptSha256 }));
+    process.exitCode = receipt.status === 'PASS' ? 0 : 1;
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/scripts/release-transaction.mjs

@@ -68,7 +68,7 @@ export const ALLOWED_TRANSITIONS = Object.freeze({
   compensated: ['github-promote-intent', 'npm-promote-intent', 'manual-intervention-required', ...ABORTABLE],
   'defaults-promoted': ['finalize-intent', 'manual-intervention-required', ...ABORTABLE],
   'finalize-intent': ['channels-converged', 'manual-intervention-required', ...ABORTABLE],
-  'manual-intervention-required': [],
+  'manual-intervention-required': [...ABORTABLE],
   'channels-converged': ['install-verified', 'abandoned', 'superseded'],
   'install-verified': [],
   abandoned: [],
@@ -506,11 +506,18 @@ export async function abortReleaseTransaction({ identity, receipts, reason, auth
 export async function finalizeReleaseTransaction({
   identity,
   aggregate,
+  verifierSha,
+  workflowRunId,
   adapter,
   privateKey,
   publicKey,
   aggregatePublicKey,
 } = {}) {
+  if (!/^[1-9][0-9]*$/.test(String(workflowRunId || ''))) throw new Error('expected workflow run ID is required');
+  if (verifierSha !== undefined && (!/^[a-f0-9]{40}$/.test(String(verifierSha))
+    || aggregate?.identity?.verifierSha !== verifierSha)) {
+    throw new Error('public verification verifier SHA differs from the expected verifier');
+  }
   if (!adapter || typeof adapter.discover !== 'function' || typeof adapter.observeSnapshot !== 'function'
     || typeof adapter.materializePublicVerificationAggregate !== 'function'
     || typeof adapter.appendReceipt !== 'function' || typeof adapter.readReceipt !== 'function') {
@@ -518,6 +525,7 @@ export async function finalizeReleaseTransaction({
   }
   const expectedAggregateIdentity = {
     ...aggregate?.identity,
+    workflowRunId: String(workflowRunId),
     sourceSha: identity?.candidateSha,
     version: identity?.version,
     tag: identity?.tag,
@@ -560,6 +568,7 @@ export async function finalizeReleaseTransaction({
       verdict: 'INSTALL_VERIFIED',
       publicVerification: {
         aggregateSha256: aggregate.aggregateSha256,
+        ...(aggregate.identity.verifierSha === undefined ? {} : { verifierSha: aggregate.identity.verifierSha }),
         aggregateAssetSha256,
         signatureAssetSha256,
         lanes: aggregate.metrics.leaves,
@@ -580,3 +589,74 @@ export async function finalizeReleaseTransaction({
   validateReceiptChain([...chain, persisted], identity, publicKey);
   return persisted;
 }
+
+// Close an unsuccessful public verification attempt without changing public bytes or truth.
+export async function abandonPublicVerificationTransaction({ identity, expected, reason, authorization,
+  recovery, failure, adapter, privateKey, publicKey } = {}) {
+  const hex = (value, length) => new RegExp(`^[a-f0-9]{${length}}$`).test(value || '');
+  const bounded = (value, max) => typeof value === 'string' && value.trim().length > 0 && value.length <= max;
+  if (!expected || expected.transactionId !== transactionIdFor(identity)
+    || !Number.isSafeInteger(expected.sequence) || expected.sequence < 0 || !hex(expected.receiptDigest, 64)) {
+    throw new Error('abandonment requires exact expected transaction, sequence, and digest');
+  }
+  if (!bounded(reason, 1024) || !bounded(authorization?.actor, 100) || !bounded(authorization?.reference, 1024)
+    || authorization.event !== 'repository_dispatch' || authorization.action !== 'abandon-public-verification'
+    || !Number.isSafeInteger(authorization.dispatchRunId) || authorization.dispatchRunId <= 0
+    || !hex(authorization.verifierSha, 40)) throw new Error('explicit abandonment authorization provenance is required');
+  if (recovery?.event !== 'repository_dispatch' || !Number.isSafeInteger(recovery.workflowId) || recovery.workflowId <= 0
+    || !Number.isSafeInteger(recovery.repositoryId) || recovery.repositoryId <= 0
+    || recovery.repository !== identity.repository || recovery.workflow !== '.github/workflows/recover-public-verification.yml'
+    || recovery.conclusion !== 'failure' || !Number.isSafeInteger(recovery.runId) || recovery.runId <= 0
+    || !Number.isSafeInteger(recovery.artifactId) || recovery.artifactId <= 0 || !hex(recovery.verifierSha, 40)
+    || recovery.artifactName !== `recovered-public-verification-${failure?.os}-${identity.candidateSha}-${recovery.runId}`) {
+    throw new Error('failed recovery provenance differs from the candidate');
+  }
+  const { failureSha256, ...failurePayload } = failure || {};
+  if (Buffer.byteLength(canonicalJson(failure || {})) > 131072 || failure?.schemaVersion !== 1
+    || failure.kind !== 'ruvnet-brain-public-verification-failure' || !['linux', 'macos', 'windows'].includes(failure.os)
+    || failure.sourceSha !== identity.candidateSha || failure.artifactSha256 !== identity.packageSha256
+    || failure.bundleSha256 !== identity.bundleSha256 || !Array.isArray(failure.failures)
+    || failure.failures.length < 1 || failure.failures.length > 3
+    || failure.failures.some((entry) => !bounded(entry.reason, 4096))
+    || (failure.verifierSha !== undefined && failure.verifierSha !== recovery.verifierSha)
+    || !hex(failureSha256, 64)
+    || crypto.createHash('sha256').update(canonicalJson(failurePayload)).digest('hex') !== failureSha256) {
+    throw new Error('bounded failed recovery evidence is invalid or belongs to another candidate');
+  }
+  const intent = { expected, reason, authorization: { actor: authorization.actor, reference: authorization.reference }, recovery, failureSha256 };
+  const intentSha256 = crypto.createHash('sha256').update(canonicalJson(intent)).digest('hex');
+  if (!adapter || ['discover', 'observeSnapshot', 'appendReceipt', 'readReceipt'].some((key) => typeof adapter[key] !== 'function')) {
+    throw new Error('abandonment adapter is incomplete');
+  }
+  const discovered = await adapter.discover(identity);
+  const chain = validateReceiptChain(discovered.receipts || [], identity, publicKey);
+  const current = chain.at(-1);
+  if (current?.state === 'abandoned') {
+    if (current.observation?.abandonment?.intentSha256 !== intentSha256) throw new Error('conflicting abandonment intent');
+    return current;
+  }
+  if (current?.schemaVersion !== 3 || current.state !== 'channels-converged'
+    || current.observation?.verdict !== 'PUBLISHED_NOT_VERIFIED'
+    || current.sequence !== expected.sequence || current.receiptDigest !== expected.receiptDigest) {
+    throw new Error('abandonment expected receipt is not the current published-unverified transaction');
+  }
+  const snapshot = await adapter.observeSnapshot(identity, discovered.matchingDrafts?.[0], { forceAssets: true });
+  if (snapshot.readError || !npmLatestIsB(snapshot, identity) || !npmCandidateExact(snapshot, identity)
+    || !githubIsB(snapshot, identity) || snapshot.github?.published !== true || snapshot.github?.latest !== true
+    || snapshot.github?.assetsExact !== true
+    || canonicalJson(snapshot.npm) !== canonicalJson(current.observation.npm)
+    || canonicalJson(snapshot.github) !== canonicalJson(current.observation.github)) {
+    throw new Error('public artifacts or channels changed before abandonment');
+  }
+  const receipt = stateReceipt({ identity, prior: current, state: 'abandoned', privateKey,
+    observation: { verdict: 'PUBLISHED_NOT_VERIFIED', abandonment: { intentSha256, ...intent, authorization, failure },
+      npm: snapshot.npm, github: snapshot.github } });
+  verifyReceipt(receipt, publicKey);
+  const name = `${RECEIPT_PREFIX}${String(receipt.sequence).padStart(4, '0')}.json`;
+  await adapter.appendReceipt(discovered.matchingDrafts?.[0] || null, receipt, name);
+  const persisted = await adapter.readReceipt(discovered.matchingDrafts?.[0] || null, receipt.sequence);
+  verifyReceipt(persisted, publicKey);
+  if (canonicalJson(persisted) !== canonicalJson(receipt)) throw new Error('abandoned receipt readback differs');
+  validateReceiptChain([...chain, persisted], identity, publicKey);
+  return persisted;
+}

package/scripts/release.mjs

@@ -31,6 +31,7 @@ import fs from 'node:fs';
 import crypto from 'node:crypto';
 import { validateProtectedPublishEnvironment, validateProtectedPublishInvocation } from './protected-release-invocation.mjs';
 import { runReleaseTransaction } from './release-transaction.mjs';
+import { materializePublicationHandoff, resolvePublicationHandoffPaths } from './release-publication-handoff.mjs';
 import { liveReleaseProvider } from './release-transaction-provider.mjs';
 import { stagedHostVerifier } from './staged-host-verifier.mjs';
 import { verifyPayload } from './release-payload.mjs';
@@ -44,6 +45,7 @@ let publicationReceiptPath = null;
 let protectedReleaseMode = 'strict';
 let verifiedPayload = null;
 let aggregateEnvelope = null;
+let publicationHandoffPaths = null;
 const c = { g: (s) => `\x1b[32m${s}\x1b[0m`, r: (s) => `\x1b[31m${s}\x1b[0m`, y: (s) => `\x1b[33m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`, dim: (s) => `\x1b[2m${s}\x1b[0m` };
 const V = () => JSON.parse(fs.readFileSync(path.join(ROOT, 'plugin/.claude-plugin/plugin.json'), 'utf8')).version;
 
@@ -222,6 +224,11 @@ if (PUBLISH) {
     console.error(`\n${c.r('✗ PROTECTED RELEASE GATE FAILED')}\n  publication receipt output must be a new file inside release-evidence\n`);
     process.exit(1);
   }
+  publicationHandoffPaths = resolvePublicationHandoffPaths({
+    root: ROOT,
+    identityPath: process.env.RUVNET_RELEASE_IDENTITY,
+    receiptPath: process.env.RUVNET_CHANNEL_RECEIPT,
+  });
   const payloadManifestPath = path.resolve(ROOT, process.env.RUVNET_CANDIDATE_PAYLOAD || '');
   const payloadSignaturePath = path.resolve(ROOT, process.env.RUVNET_CANDIDATE_PAYLOAD_SIGNATURE || '');
   const aggregatePath = path.resolve(ROOT, process.env.RUVNET_AGGREGATE_ENVELOPE || '');
@@ -375,6 +382,7 @@ if (PUBLISH) {
   };
   const privatePem = process.env.RUVNET_SIGNING_KEY;
   if (!privatePem) throw new Error('RUVNET_SIGNING_KEY is required for signed transaction receipts');
+  const publicKey = crypto.createPublicKey(fs.readFileSync(path.join(ROOT, 'keys/ruvnet-brain-signing.pub.pem'), 'utf8'));
   const finalReceipt = await runReleaseTransaction({
     identity, assets, adapter: liveReleaseProvider({
       root: ROOT,
@@ -382,10 +390,11 @@ if (PUBLISH) {
       publicationReceipt: process.env.RUVNET_PUBLICATION_RECEIPT,
     }),
     privateKey: crypto.createPrivateKey(privatePem),
-    publicKey: crypto.createPublicKey(fs.readFileSync(path.join(ROOT, 'keys/ruvnet-brain-signing.pub.pem'), 'utf8')),
+    publicKey,
     hostVerifier: stagedHostVerifier({ assets, identity }),
   });
   if (finalReceipt.state !== 'channels-converged') throw new Error(`release transaction stopped at ${finalReceipt.state}`);
+  materializePublicationHandoff({ paths: publicationHandoffPaths, identity, receipt: finalReceipt, publicKey });
 } else {
   step('D', 'remote staged release transaction — SKIPPED (check-only; pass --publish to publish)');
 }

package/scripts/remedy-registry.mjs

@@ -103,26 +103,19 @@ export const REMEDIES = [
     inverse: () => ({ kind: K.RESTORE_STORE_BACKUPS }),
   },
   {
-    // THE CAPABILITY BRIDGE'S ONLY CURRENT MEMBER. buildCapabilityRecommendations() in
-    // console-engine.mjs offers `enable:memory-distillation` only while the capability is OFF; this
-    // is the executor behind it. See distill-project.mjs's header for why THIS script and not bare
-    // `ruflo memory distill run`: the wrapper snapshots first, fails closed on a receipt-write
-    // failure, and its `--restore` is the tested inverse (proven 644→648→644→648, 2026-07-24).
+    // Retained for explicit execution and existing receipts, not offered as reversible.
+    // The restore command refuses unsafe replacement; historical roundtrips do not authorize it.
     key: 'enable-memory-distillation',
-    autoEligible: true,
-    summary: "mine this project's stored memories into reusable patterns (snapshots first; reversible)",
+    autoEligible: false,
+    summary: "mine this project's stored memories into reusable patterns (snapshots first; automatic undo unavailable)",
     match: (id) => (id === 'enable:memory-distillation' ? {} : null),
     // This console instance is always scoped to ONE project — the directory it was started in — the
     // same assumption the memory-index/learning-flush/learning-train remedies above already make.
     // `usesServerProject` asks onboarding-console.mjs (impure, process-aware) to supply that directory
     // at call time; this file stays pure and never reads process.cwd() itself (see header).
     plan: () => ({ script: 'scripts/distill-project.mjs', args: [], usesServerProject: true }),
-    // `--restore` with no path argument uses distill-project.mjs's OWN newestSnapshot() lookup inside
-    // this project's `.swarm/backups` — the exact mechanism its header proves end to end. Re-deriving
-    // which snapshot to restore here, instead of asking the tool that took it, is the kind of
-    // duplicate implementation this project has already been burned by once (ADR-047's rejected
-    // "offered command and promised undo live on different execution paths" bug).
-    inverse: () => ({ kind: K.RESTORE_PROJECT_DISTILL }),
+    inverse: () => ({ kind: K.RESTORE_PROJECT_DISTILL, available: false,
+      human: 'automatic undo is unavailable; retain the snapshot and coordinate offline SQLite recovery with all database users stopped' }),
   },
   {
     key: 'stack-sync',

package/scripts/retrieval-canary.mjs

@@ -2,10 +2,74 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import readline from 'node:readline';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { canonicalJson, digest, validateCoverageLedger } from './coverage-integrity.mjs';
 
+// Both release phases resolve against an explicit installed context, never the checkout.
+export async function resolveInstalledCanaryCitation({ kbDir, matched, expected, passageFileDigests = new Map() }) {
+  if (!path.isAbsolute(kbDir || '')) throw new Error('installed canary KB path must be absolute');
+  if (String(matched?.repo || '').toLowerCase() !== expected.repo || matched?.path !== expected.path) return { resolved: false };
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(expected.repo)) throw new Error('installed citation repository violates containment');
+  const rootStat = fs.lstatSync(kbDir);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || fs.realpathSync(kbDir) !== path.resolve(kbDir)) {
+    throw new Error('installed canary KB root or parent is a symlink; canonical containment required');
+  }
+  const files = [path.join(kbDir, `${expected.repo}.passages.jsonl`), path.join(kbDir, `${expected.repo}.big.passages.jsonl`)]
+    .filter((file) => { try { fs.lstatSync(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } });
+  for (const file of files) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || path.dirname(fs.realpathSync(file)) !== kbDir) {
+      throw new Error('installed citation file is a symlink or violates containment');
+    }
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stream = fs.createReadStream(file, { fd, autoClose: false });
+    const hash = crypto.createHash('sha256');
+    stream.on('data', (bytes) => hash.update(bytes));
+    const rows = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let passageSha256 = null;
+    try {
+      for await (const line of rows) {
+        let record;
+        try { record = JSON.parse(line); } catch { continue; }
+        if (record?.path !== expected.path) continue;
+        if (digest(record) !== expected.passageSha256) continue;
+        const text = record.fullText || record.text;
+        if (typeof text !== 'string' || !text || typeof matched.text !== 'string' || !matched.text.includes(text)) continue;
+        passageSha256 = expected.passageSha256;
+      }
+      const after = fs.lstatSync(file);
+      const opened = fs.fstatSync(fd);
+      if (after.isSymbolicLink() || after.dev !== stat.dev || after.ino !== stat.ino
+        || opened.ino !== stat.ino || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs
+        || after.ctimeMs !== stat.ctimeMs) throw new Error('installed citation changed during verification');
+      const passageFileSha256 = hash.digest('hex');
+      passageFileDigests.set(file, passageFileSha256);
+      if (passageSha256) return { resolved: true, evidence: { passageSha256, passageFileSha256,
+        hitContentSha256: crypto.createHash('sha256').update(matched.text).digest('hex') } };
+    } finally {
+      rows.close();
+      await new Promise((resolve, reject) => stream.close((error) => error ? reject(error) : resolve()));
+    }
+  }
+  return { resolved: false };
+}
+
+function expectedSources(expected) {
+  return [{ path: expected.path, passageSha256: expected.passageSha256 }, ...(expected.alternatives || [])];
+}
+function validExpectedSources(expected) {
+  if (!expected || !['passageSha256,path', 'alternatives,passageSha256,path'].includes(Object.keys(expected).sort().join(','))) return false;
+  if (expected.alternatives !== undefined && (!Array.isArray(expected.alternatives)
+    || expected.alternatives.length < 1 || expected.alternatives.length > 8)) return false;
+  const sources = expectedSources(expected);
+  return new Set(sources.map((source) => source?.path)).size === sources.length && sources.every((source) =>
+    source && Object.keys(source).sort().join(',') === 'passageSha256,path'
+    && typeof source.path === 'string' && source.path && !path.isAbsolute(source.path)
+    && !source.path.split(/[\\/]/).includes('..') && HEX64.test(String(source.passageSha256 || '')));
+}
+
 const HEX40 = /^[a-f0-9]{40}$/;
 const HEX64 = /^[a-f0-9]{64}$/;
 
@@ -96,10 +160,7 @@ export function validateRetrievalQueryEvidence(evidence) {
     if (Object.keys(row || {}).sort().join(',') !== 'expected,query,recordSha256'
       || typeof row.query !== 'string' || row.query !== row.query.trim().replace(/\s+/g, ' ')
       || normalized.length < 24 || seenQueries.has(normalized)
-      || !expected || Object.keys(expected).sort().join(',') !== 'passageSha256,path'
-      || typeof expected.path !== 'string' || !expected.path || path.isAbsolute(expected.path)
-      || expected.path.split(/[\\/]/).includes('..')
-      || !HEX64.test(String(expected.passageSha256 || ''))
+      || !validExpectedSources(expected)
       || row.recordSha256 !== digest({ store, query: row.query, expected })) {
       throw new Error(`independent retrieval query evidence for ${store} is malformed`);
     }
@@ -187,7 +248,8 @@ export function validateRetrievalCanaryPlan(plan) {
     throw new Error('oracle denominator differs from eligible coverage');
   }
   if (new Set(ids).size !== ids.length) throw new Error('retrieval canary plan has duplicate case ids');
-  if ((!plan.cases.some(({ cohort }) => cohort === 'delta') && plan.noDelta !== true)
+  const hasDelta = plan.cases.some(({ cohort }) => cohort === 'delta');
+  if ((!hasDelta && plan.noDelta !== true) || (hasDelta && plan.noDelta === true)
     || !plan.cases.some(({ cohort }) => cohort === 'legacy')) {
     throw new Error('retrieval canary plan requires delta and legacy cohorts');
   }
@@ -316,12 +378,15 @@ export function buildRetrievalCanaryPlan({ coverage, baseline, candidate, covera
     if (!strata.has(stratum)) strata.set(stratum, []);
     strata.get(stratum).push(entry);
   });
+  // Source-only releases retain the same corpus sample; the plan still seals exact release bytes.
+  const samplingGeneration = coverage.kind === 'ruvnet-brain-release-coverage'
+    ? coverage.corpusCoverage.coverageGeneration : coverageGeneration;
   const sampleCount = Math.min(legacyPool.length, legacySampleSize ?? Math.max(10, Math.ceil(eligible.length * 0.1)));
   if (sampleCount < strata.size) throw new Error(`legacy sample must cover all ${strata.size} passage-count strata`);
   const selected = [];
   for (const [stratum, entries] of strata) {
-    entries.sort((a, b) => digest(`${coverageGeneration}:${stratum}:${storeOf(a.row)}`)
-      .localeCompare(digest(`${coverageGeneration}:${stratum}:${storeOf(b.row)}`)));
+    entries.sort((a, b) => digest(`${samplingGeneration}:${stratum}:${storeOf(a.row)}`)
+      .localeCompare(digest(`${samplingGeneration}:${stratum}:${storeOf(b.row)}`)));
     selected.push({ ...entries.shift(), stratum });
   }
   while (selected.length < sampleCount) {
@@ -338,9 +403,8 @@ export function buildRetrievalCanaryPlan({ coverage, baseline, candidate, covera
       const store = storeOf(row);
       const observedPassageCount = passageCount ?? passages.get(store).length;
       const evidence = queryEvidence.queries[store];
-      const matches = passages.get(store).filter((row) => row.path === evidence?.expected?.path
-        && digest(row) === evidence.expected.passageSha256);
-      if (!evidence || matches.length !== 1) {
+      if (!evidence || expectedSources(evidence.expected).some((source) =>
+        passages.get(store).filter((row) => row.path === source.path && digest(row) === source.passageSha256).length !== 1)) {
         throw new Error(`${store} has no sealed independent query evidence`);
       }
       return {
@@ -430,10 +494,12 @@ export function validateRetrievalCanaryReceipt(receipt, { plan, requireAcceptanc
   for (const row of receipt.cases) {
     const expected = plan.cases.find(({ id }) => id === row.id)?.expected;
     const ranked = row.retrievalHit ? row.citations?.[row.rank - 1] : null;
+    const accepted = expectedSources(expected).find((source) => source.path === ranked?.path);
     if (row.retrievalHit && (String(ranked?.repo || '').toLowerCase() !== expected.repo
-      || ranked?.path !== expected.path
-      || (row.citationResolved === true && (row.citationEvidence?.passageSha256 !== expected.passageSha256
-        || !HEX64.test(String(row.citationEvidence?.passageFileSha256 || '')))))) {
+      || !accepted
+      || (row.citationResolved === true && (row.citationEvidence?.passageSha256 !== accepted.passageSha256
+        || !HEX64.test(String(row.citationEvidence?.passageFileSha256 || ''))
+        || (ranked.contentSha256 !== undefined && row.citationEvidence?.hitContentSha256 !== ranked.contentSha256))))) {
       throw new Error(`retrieval canary ${row.id} hit or citation evidence differs from the sealed plan`);
     }
   }
@@ -448,7 +514,9 @@ export function validateRetrievalCanaryReceipt(receipt, { plan, requireAcceptanc
     deltaHits: delta.filter(({ retrievalHit }) => retrievalHit === true).length,
     deltaCitations: delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length,
     recallAt10: hits / receipt.cases.length,
-    deltaCitationRate: delta.length ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length / delta.length : 0,
+    deltaCitationRate: delta.length
+      ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length / delta.length
+      : plan.noDelta === true ? 1 : 0,
     unknown,
     skipped,
   };
@@ -478,12 +546,14 @@ export async function runRetrievalCanaries({ plan, sourceSha, artifactSha256, ca
         const rows = resultRows(await search({ query: canary.query, k: 10 }));
         const top = rows.slice(0, 10);
         const rank = top.findIndex((row) => String(row?.repo || '').toLowerCase() === canary.expected.repo
-          && row?.path === canary.expected.path);
+          && expectedSources(canary.expected).some((source) => row?.path === source.path));
         const matched = rank >= 0 ? top[rank] : null;
-        const resolved = matched ? await citationResolver(matched, canary.expected) : { resolved: false };
+        const accepted = matched ? expectedSources(canary.expected).find((source) => source.path === matched.path) : null;
+        const resolved = matched ? await citationResolver(matched, { repo: canary.expected.repo, ...accepted }) : { resolved: false };
         cases[index] = { id: canary.id, cohort: canary.cohort, status: 'COMPLETED', retrievalHit: rank >= 0,
           citationResolved: resolved?.resolved === true, citationEvidence: resolved?.evidence || null,
-          rank: rank >= 0 ? rank + 1 : null, citations: top.map(({ repo, path: hitPath }) => ({ repo, path: hitPath })) };
+          rank: rank >= 0 ? rank + 1 : null, citations: top.map(({ repo, path: hitPath, contentSha256 }) => ({ repo, path: hitPath,
+            ...(contentSha256 ? { contentSha256 } : {}) })) };
       } catch (error) {
         cases[index] = { id: canary.id, cohort: canary.cohort, status: 'UNKNOWN', retrievalHit: false,
           citationResolved: false, citationEvidence: null, rank: null, citations: [], error: error.message };
@@ -494,7 +564,10 @@ export async function runRetrievalCanaries({ plan, sourceSha, artifactSha256, ca
   const hits = cases.filter(({ retrievalHit }) => retrievalHit).length;
   const metrics = { total: cases.length, hits, deltaTotal: delta.length, deltaHits: delta.filter(({ retrievalHit }) => retrievalHit).length,
     deltaCitations: delta.filter(({ retrievalHit, citationResolved }) => retrievalHit && citationResolved).length,
-    recallAt10: hits / cases.length, deltaCitationRate: delta.length ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit && citationResolved).length / delta.length : 0,
+    recallAt10: hits / cases.length,
+    deltaCitationRate: delta.length
+      ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit && citationResolved).length / delta.length
+      : plan.noDelta === true ? 1 : 0,
     unknown: cases.filter(({ status }) => status === 'UNKNOWN').length,
     skipped: cases.filter(({ status }) => status === 'SKIPPED').length };
   const payload = { schemaVersion: 1, kind: 'ruvnet-brain-retrieval-canary-receipt', sourceSha, artifactSha256,

package/scripts/selfcheck.mjs

@@ -477,7 +477,7 @@ export function assertContract({ rec, measurement, mode, timeoutSec }) {
 }
 
 // ── §4 THE BATTERY: every installed registration × every stdin regime ───────────────────────────
-export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tmpdir(), regimes = STDIN_REGIMES, surface = null, env = {} } = {}) {
+export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tmpdir(), regimes = STDIN_REGIMES, surface = null, env = {}, inspectOnly = false } = {}) {
   const reg = await loadRegistry();
   const s = surface ?? resolveInstalledSurface({ home, repo });
   if (!s.ok) return { ok: false, reason: s.reason, violations: [], results: [] };
@@ -487,6 +487,7 @@ export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tm
   const { contracts } = reg.loadContracts(s.root);
 
   const registrations = readInstalledRegistrations(s.hooksFile);
+  if (inspectOnly) return { ok: true, surface: s, registrations, violations: [], results: [] };
   const violations = [];
   const results = [];
 
@@ -614,13 +615,20 @@ export async function selfCheck({ home = os.homedir(), repo = null, cwd = os.tmp
   }
 
   // (b) THE BATTERY
-  const battery = await runBattery({ home, repo, cwd, regimes });
+  const battery = await runBattery({ home, repo, cwd, regimes, inspectOnly: true });
   if (!battery.ok) {
     lines.push(`hooks: ${battery.reason}`);
     violations.push({ kind: 'no-plugin', where: 'hooks', detail: battery.reason });
   } else {
     violations.push(...battery.violations);
-    lines.push(`hooks: ${battery.registrations.length} registrations from ${battery.surface.source}, ${regimes.length} stdin regimes each (${battery.results.length} firings)`);
+    if (battery.registrations.length !== 0) {
+      violations.push({
+        kind: 'automatic-registration',
+        where: battery.surface.source,
+        detail: `${battery.registrations.length} retired Brain lifecycle registration(s) remain installed`,
+      });
+    }
+    lines.push(`hooks: ${battery.registrations.length} automatic registrations from ${battery.surface.source}; zero is the required retired state`);
   }
 
   // (c) COEXISTENCE — reported, never charged to the user
@@ -656,7 +664,7 @@ export function formatVerdict(result, { color = null } = {}) {
   const out = [];
   for (const l of result.lines) out.push(`  ${c.dim(l)}`);
   if (!result.violations.length) {
-    out.push(`  ${c.green('✓ Self-check passed.')} Every shipped hook answered inside its contract on this machine.`);
+    out.push(`  ${c.green('✓ Self-check passed.')} The installed Brain surface has zero automatic lifecycle registrations.`);
     return out.join('\n');
   }
   out.push(`  ${c.red(`✗ Self-check FAILED — ${result.violations.length} contract violation(s):`)}`);

package/scripts/snapshot-freshness.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * snapshot-freshness.mjs — "a claimed backup is not a found backup" as a shared, pure function.
+ *
+ * `distill-project.mjs` established this discipline (PR #192): `ruflo memory backup` exiting 0
+ * proves nothing about whether a NEW file actually landed — a stale snapshot from a prior run
+ * sitting in the same directory is otherwise indistinguishable from a genuine fresh one, and a
+ * caller that trusts the exit code alone can proceed to mutate state on a false undo guarantee.
+ * Extracted here so `health-repair.mjs`'s fleet distillation (a second, independent caller of
+ * `ruflo memory backup` per store) can share the exact same proof instead of re-deriving it —
+ * duplicating this logic once already cost a real, shipped defect (see the 2026-08-29 Dream Cycle
+ * report, "Next steps #1").
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 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.
+export const MTIME_GRACE_MS = 1500;
+
+/**
+ * The newest matching snapshot file in `dir`, or null. With `sinceMs`, only a file whose mtime is
+ * no older than that moment (minus the grace window) counts. Mutating callers also provide a
+ * pre-backup inventory, so an unchanged prior snapshot cannot count within that grace. Callers that
+ * legitimately want the newest snapshot ever (e.g. a restore path) pass no `sinceMs`.
+ */
+export function snapshotInventory(dir) {
+  let root;
+  try { root = fs.lstatSync(dir); }
+  catch (error) { if (error.code === 'ENOENT') return new Map(); throw error; }
+  if (!root.isDirectory() || root.isSymbolicLink()) throw new Error('Backup destination is not a regular directory');
+  const inventory = new Map();
+  for (const name of fs.readdirSync(dir)) {
+    if (!/\.(db|sqlite|bak)$/i.test(name) && !/memory.*\d/.test(name)) continue;
+    const file = path.join(dir, name);
+    try {
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || !stat.size) continue;
+      inventory.set(file, {
+        path: file, mtimeMs: stat.mtimeMs,
+        identity: [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(':'),
+      });
+    } catch { /* a disappearing candidate is not a located backup */ }
+  }
+  return inventory;
+}
+
+export function newestSnapshot(dir, sinceMs = 0, graceMs = MTIME_GRACE_MS, before = null) {
+  try {
+    const files = [...snapshotInventory(dir).values()]
+      .filter(file => file.mtimeMs >= sinceMs - graceMs
+        && (!before || before.get(file.path)?.identity !== file.identity))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return files[0]?.path ?? null;
+  } catch { return null; }
+}