ruvnet-brain 4.3.26 → 4.3.28

package/scripts/public-verification-inputs.mjs

@@ -113,6 +113,18 @@ function exactNamedFile(root, name, label) {
   return trustedFile(path.join(root, name), label);
 }
 
+function validHistoricalGenerationLedger(ledger, names) {
+  const legacy = ledger?.schemaVersion === 1;
+  const runtime = ledger?.schemaVersion === 2
+    && ledger?.kind === 'ruvnet-brain-runtime-generation-ledger'
+    && HEX40.test(String(ledger?.sourceSnapshot || ''));
+  return (legacy || runtime)
+    && typeof ledger?.brainVersion === 'string' && Boolean(ledger.brainVersion)
+    && typeof ledger?.releaseTag === 'string' && Boolean(ledger.releaseTag)
+    && names.length > 0
+    && new Set(names.map((name) => name.toLowerCase())).size === names.length;
+}
+
 function validateCandidate({ root, bundleFile, packageFile }) {
   const coverageFile = trustedFile(path.join(root, 'COVERAGE.json'), 'candidate release coverage');
   const coverageBytes = fs.readFileSync(coverageFile);
@@ -176,9 +188,7 @@ function retrospectiveBaselineFromTree({ extractedRoot, bundleFile, expectedTag,
   const root = path.dirname(ledgerFile);
   const { value: ledger } = readJson(ledgerFile, 'historical baseline generation ledger');
   const names = Object.keys(ledger?.stores || {}).sort();
-  if (ledger.schemaVersion !== 1 || typeof ledger.brainVersion !== 'string' || !ledger.brainVersion
-    || typeof ledger.releaseTag !== 'string' || !ledger.releaseTag || !names.length
-    || new Set(names.map((name) => name.toLowerCase())).size !== names.length) {
+  if (!validHistoricalGenerationLedger(ledger, names)) {
     fail('historical baseline generation ledger is malformed');
   }
   const archive = namedIdentity(bundleFile);
@@ -245,9 +255,7 @@ function observedBaselineFromTree({ extractedRoot, bundleFile, expectedTag, expe
   const root = path.dirname(ledgerFile);
   const { value: ledger } = readJson(ledgerFile, 'historical baseline generation ledger');
   const ledgerNames = Object.keys(ledger?.stores || {}).sort();
-  if (ledger.schemaVersion !== 1 || typeof ledger.brainVersion !== 'string' || !ledger.brainVersion
-    || typeof ledger.releaseTag !== 'string' || !ledger.releaseTag || !ledgerNames.length
-    || new Set(ledgerNames.map((name) => name.toLowerCase())).size !== ledgerNames.length) {
+  if (!validHistoricalGenerationLedger(ledger, ledgerNames)) {
     fail('historical baseline generation ledger is malformed');
   }
   const archive = namedIdentity(bundleFile);

package/scripts/publication-receipt.mjs

@@ -15,7 +15,9 @@ import { spawn, spawnSync } from 'node:child_process';
 // `fixtures.claude` described the same fixture and nothing could tell. The richer
 // post-publication proofs below (payload assertions, MCP wiring, SOURCE.json, rpcSearch)
 // stay here — they are this side's job, not duplication.
-import { HOST_MODES, RECEIPT_MODE_NAMES, MODE_FROM_RECEIPT_NAME, classifyDoctor, VARIANTS, createInstalledMcpSession } from './host-install-matrix.mjs';
+import { HOST_MODES, RECEIPT_MODE_NAMES, MODE_FROM_RECEIPT_NAME, classifyDoctor, VARIANTS,
+  createInstalledMcpSession, HOST_WARMUP_TIMEOUT_MS, RELEASE_SEARCH_DEADLINE_MS, SELF_STORE_PROOF_QUERY,
+  SELF_STORE_PROOF_K } from './host-install-matrix.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { evaluateCandidateReceipt, evaluatePublicationReceipt } from './release-proof.mjs';
 import { verifyPayload } from './release-payload.mjs';
@@ -30,8 +32,21 @@ import { parseRetrievalResult } from '../kb/retrieval-result.mjs';
 
 const REPO = 'stuinfla/ruvnet-brain';
 const PACKAGE = 'ruvnet-brain';
-const DEADLINE_MS = 30_000;
-const WARMUP_TIMEOUT_MS = 300_000;
+const DEADLINE_MS = RELEASE_SEARCH_DEADLINE_MS;
+const WARMUP_TIMEOUT_MS = HOST_WARMUP_TIMEOUT_MS;
+
+export async function runMeasuredHostSearches(hosts, search, { warmup, after } = {}) {
+  const results = new Map();
+  for (const host of hosts) {
+    try {
+      await warmup?.(host);
+      results.set(host.mode, await search(host, DEADLINE_MS));
+    } finally {
+      await after?.(host);
+    }
+  }
+  return results;
+}
 
 const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -524,40 +539,55 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
         };
       }));
 
-      // Keep one MCP worker per host. The first search on each worker may load the local model,
-      // but all later proofs reuse the initialized process instead of paying that startup cost
-      // again. The fixed deadline remains strict for each actual search operation.
-      for (const { mode, context } of hostResults) {
-        const publicMode = MODE_FROM_RECEIPT_NAME[mode];
-        mcpSessions.set(publicMode, createInstalledMcpSession({
-          serverPath: findMcpServer(context.home), env: context.env, timeout: WARMUP_TIMEOUT_MS,
-        }));
-      }
       const searched = new Map();
       const searchInstalledHost = async ({ mode }, timeoutMs) => {
         const publicMode = MODE_FROM_RECEIPT_NAME[mode];
         const session = mcpSessions.get(publicMode);
+        const phase = timeoutMs > DEADLINE_MS ? 'warmup' : 'measured search';
+        console.log(`Public verification: ${mode} ${phase} (limit ${timeoutMs}ms)`);
         const result = await session.search({
-          query: 'How does RuvNet Brain prove a public release artifact?', k: 5,
+          query: SELF_STORE_PROOF_QUERY, k: SELF_STORE_PROOF_K,
           timeoutMs,
         });
         if (result.error || !result.mcpResult || (Object.hasOwn(result, 'status') && result.status !== 0)) {
-          throw new Error(`installed Brain search failed for ${mode}: ${result.error?.message || 'no MCP result'}`);
+          throw new Error(`installed Brain ${phase} failed for ${mode} after ${timeoutMs}ms: ${result.error?.message || 'no MCP result'}`);
         }
-        if (!/repo=/i.test(result.stdout) || !/path\s*:/i.test(result.stdout)) {
+        if (!/repo\s*=\s*ruvnet-brain/i.test(result.stdout) || !/path\s*:/i.test(result.stdout)) {
           throw new Error(`installed Brain search returned no source citation for ${mode}`);
         }
         return result;
       };
-      // Warm each worker serially. The model cache is shared, but simultaneous first-loads can
-      // contend on slower runners (the macOS Codex-only timeout that motivated this path). The
-      // warm-up is bounded generously and is never used as the release latency measurement.
-      for (const host of hostResults) await searchInstalledHost(host, WARMUP_TIMEOUT_MS);
-      // Once initialized, the three steady-state checks can run in parallel and are each held to
-      // the strict public deadline that the receipt and aggregate validators enforce.
-      await Promise.all(hostResults.map(async (host) => {
-        searched.set(host.mode, await searchInstalledHost(host, DEADLINE_MS));
-      }));
+      // Warm and measure one isolated host at a time, then retire its model-backed worker before
+      // moving to the next host. Serial RPCs alone are insufficient: keeping three independent
+      // workers resident still competes for memory and CPU during the measured query on macOS.
+      const measuredSearches = await runMeasuredHostSearches(hostResults, searchInstalledHost, {
+        warmup: async ({ mode, context }) => {
+          for (const [openMode, session] of mcpSessions) {
+            if (openMode !== MODE_FROM_RECEIPT_NAME[mode]) {
+              await session.close();
+              mcpSessions.delete(openMode);
+            }
+          }
+          const publicMode = MODE_FROM_RECEIPT_NAME[mode];
+          if (!mcpSessions.has(publicMode)) {
+            mcpSessions.set(publicMode, createInstalledMcpSession({
+              serverPath: findMcpServer(context.home), env: context.env, timeout: WARMUP_TIMEOUT_MS,
+            }));
+          }
+          // The generous bound is for one-time readiness/model warmup only; the following
+          // measured query still has the unchanged strict 30-second deadline.
+          await searchInstalledHost({ mode }, WARMUP_TIMEOUT_MS);
+        },
+        after: async ({ mode }) => {
+          const publicMode = MODE_FROM_RECEIPT_NAME[mode];
+          if (mode !== 'dual') {
+            const session = mcpSessions.get(publicMode);
+            if (session) await session.close();
+            mcpSessions.delete(publicMode);
+          }
+        },
+      });
+      for (const [mode, result] of measuredSearches) searched.set(mode, result);
       await Promise.all(hostResults.map(async ({ context, installer }) => {
         await commandAsync(process.execPath, [installer, '--doctor', '--hooks'], {
           env: context.env, cwd: packageRoot, timeout: 300_000, stdio: 'inherit',
@@ -590,9 +620,9 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
       // installed process that passed the host canary instead of starting a cold verifier child.
       const session = mcpSessions.get(mode);
       const result = session
-        ? await session.search({ query: 'How does RuvNet Brain prove a public release artifact?', k: 5, timeoutMs: DEADLINE_MS })
+        ? await session.search({ query: SELF_STORE_PROOF_QUERY, k: SELF_STORE_PROOF_K, timeoutMs: DEADLINE_MS })
         : await rpcSearch(server, installContext.env,
-          'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS);
+          SELF_STORE_PROOF_QUERY, SELF_STORE_PROOF_K, DEADLINE_MS);
       if (result.error || !result.mcpResult || (Object.hasOwn(result, 'status') && result.status !== 0)) {
         throw new Error(`installed Brain search failed for ${mode}: ${result.error?.message || 'no MCP result'}`);
       }
@@ -604,13 +634,24 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
     async searchInstalled({ mode, query, k }) {
       const context = installContexts.get(mode);
       if (!context) throw new Error(`${mode} public host is not installed`);
-      // Keep one MCP worker per installed host. Starting a fresh worker for every canary reloads
-      // the local embedding model repeatedly and can exceed the fixed 30-second public deadline
-      // on macOS, even when the installed Brain itself is healthy.
+      // Retrieval canaries run mode-by-mode. Retire the prior mode before opening this host so
+      // only one model-backed MCP worker can consume resources at a time.
+      for (const [openMode, openSession] of mcpSessions) {
+        if (openMode !== mode) {
+          await openSession.close();
+          mcpSessions.delete(openMode);
+        }
+      }
       let session = mcpSessions.get(mode);
       if (!session) {
-        session = createInstalledMcpSession({ serverPath: findMcpServer(context.home), env: context.env, timeout: DEADLINE_MS });
+        session = createInstalledMcpSession({ serverPath: findMcpServer(context.home), env: context.env, timeout: WARMUP_TIMEOUT_MS });
         mcpSessions.set(mode, session);
+        const warmed = await session.search({
+          query: SELF_STORE_PROOF_QUERY, k: SELF_STORE_PROOF_K, timeoutMs: WARMUP_TIMEOUT_MS,
+        });
+        if (warmed.error || !warmed.mcpResult || (Object.hasOwn(warmed, 'status') && warmed.status !== 0)) {
+          throw new Error(`installed Brain warmup failed for ${mode}: ${warmed.error?.message || 'no MCP result'}`);
+        }
       }
       const result = await session.search({ query, k, timeoutMs: DEADLINE_MS });
       return parseRetrievalResult(result.mcpResult, { query, k });

package/scripts/qe/ux-suite.mjs

@@ -175,13 +175,22 @@ export function overBudgetRows(results, budgets) {
   return (results || []).filter((r) => timingFailure(r.label, r.ms, budgets[r.label]) !== null);
 }
 
+/** Failed or missing acceptance rows are hard failures and must participate in attempt ranking. */
+export function failedAcceptanceRows(acceptance) {
+  if (!Array.isArray(acceptance) || acceptance.length === 0) return [{ label: 'acceptance: NOT RUN' }];
+  return acceptance.filter((row) => row?.pass !== true);
+}
+
 /**
- * Rank two attempts: fewer over-budget rows wins; ties break on lower total measured ms, so a
- * genuinely faster run is preferred over a marginally-less-bad one.
+ * Rank two attempts: fewer failed hard acceptance checks wins first, then fewer over-budget
+ * timings, with the lower measured total breaking remaining ties.
  */
 export function betterAttempt(a, b, budgets) {
   if (!a) return b;
   if (!b) return a;
+  const aa = failedAcceptanceRows(a.acceptance).length;
+  const ba = failedAcceptanceRows(b.acceptance).length;
+  if (aa !== ba) return aa < ba ? a : b;
   const oa = overBudgetRows(a.results, budgets).length;
   const ob = overBudgetRows(b.results, budgets).length;
   if (oa !== ob) return oa < ob ? a : b;
@@ -190,8 +199,8 @@ export function betterAttempt(a, b, budgets) {
 }
 
 /**
- * Run the render probe until an attempt clears every budget, or ATTEMPTS is exhausted; return the
- * best attempt seen, annotated with how many attempts it took.
+ * Run the render probe until timings, hard acceptance checks and harness notes are clean, or
+ * ATTEMPTS is exhausted; return the best attempt seen, annotated with how many attempts it took.
  */
 export async function runRenderProbeBestOf(budgets, {
   attempts = RENDER_ATTEMPTS,
@@ -200,9 +209,12 @@ export async function runRenderProbeBestOf(budgets, {
   let best = null;
   for (let i = 1; i <= attempts; i++) {
     const attempt = await run();
+    const acceptanceFailures = failedAcceptanceRows(attempt.acceptance);
     // `notes` means the probe could not produce a reading at all — a harness failure, not slowness.
     // Retrying it is legitimate for the same reason, but it must never be silently swallowed.
-    if (!overBudgetRows(attempt.results, budgets).length && !(attempt.notes || []).length) {
+    if (!overBudgetRows(attempt.results, budgets).length
+      && acceptanceFailures.length === 0
+      && !(attempt.notes || []).length) {
       return { ...attempt, attemptsUsed: i, attemptsAllowed: attempts };
     }
     best = betterAttempt(best, attempt, budgets);

package/scripts/refresh-capability-only-store.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Rebuild ruOS's release store from the curated capability summary, never from repository source.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { buildCorpus } from '../kb/forge-corpus.mjs';
+import { loadRvf } from '../kb/resolve-deps.mjs';
+import { CAPABILITY_RETIRED_SUFFIXES, isCapabilityOnly } from '../kb/capability-only.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const NAME = 'cognitum-ruos';
+const MODEL = 'Xenova/bge-base-en-v1.5';
+const DIMENSIONS = 768;
+
+function writeJson(file, value) {
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function prepareCapabilityOnlyInputs(assetsDir) {
+  const dir = path.resolve(assetsDir);
+  if (!fs.statSync(dir).isDirectory()) throw new Error(`assets directory is invalid: ${dir}`);
+  const corpus = buildCorpus({ repo: dir, name: NAME });
+  if (corpus.chunks.length !== 1 || corpus.chunks[0].path !== 'CAPABILITIES.md'
+    || corpus.chunks[0].kind !== 'doc') {
+    throw new Error('curated ruOS source must produce exactly one CAPABILITIES.md document');
+  }
+
+  for (const suffix of CAPABILITY_RETIRED_SUFFIXES) fs.rmSync(path.join(dir, `${NAME}${suffix}`), { force: true });
+  for (const file of fs.readdirSync(dir)) {
+    if (file.startsWith(`${NAME}.big.vecs.`) || file.startsWith(`${NAME}.big.progress.`)) {
+      fs.rmSync(path.join(dir, file), { force: true });
+    }
+  }
+  const chunk = corpus.chunks[0];
+  writeJsonLines(path.join(dir, `${NAME}.passages.jsonl`), [{
+    id: chunk.id, text: chunk.text, path: chunk.path, title: chunk.title,
+  }]);
+  writeJson(path.join(dir, `${NAME}.meta.json`), {
+    model: MODEL, dimensions: DIMENSIONS, metric: 'cosine', generated: new Date().toISOString(),
+    entries: { [chunk.id]: { path: chunk.path, kind: chunk.kind, title: chunk.title, chunk: '1/1', preview: chunk.preview } },
+  });
+  return { dir, sourceText: chunk.text, id: chunk.id };
+}
+
+// Historical v4.3.26 Brain self-store embedded the implementation primer. Remove those
+// vectors from the copied seed and bind the rewritten bytes before packaging.
+export async function pruneCapabilityOnlySelfStore(assetsDir, { RvfDatabase = null } = {}) {
+  const dir = path.resolve(assetsDir);
+  const passagesFile = path.join(dir, 'ruvnet-brain.passages.jsonl');
+  const metaFile = path.join(dir, 'ruvnet-brain.meta.json');
+  const rvfFile = path.join(dir, 'ruvnet-brain.big.rvf');
+  const ledgerFile = path.join(dir, 'RVF-GENERATIONS.json');
+  const rows = fs.readFileSync(passagesFile, 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse);
+  const removed = rows.filter(row => /(?:^|\/)cognitum-ruos-primer\.md$/i.test(row.path || ''));
+  if (!removed.length) return { removed: 0 };
+  if (!RvfDatabase) ({ mod: { RvfDatabase } } = loadRvf());
+  const db = await RvfDatabase.open(rvfFile);
+  try {
+    await db.delete(removed.map(row => row.id));
+    await db.compact();
+  } finally { await db.close(); }
+  const kept = rows.filter(row => !removed.some(item => item.id === row.id));
+  writeJsonLines(passagesFile, kept);
+  const meta = JSON.parse(fs.readFileSync(metaFile, 'utf8'));
+  const removedIds = new Set(removed.map(row => row.id));
+  for (const row of removed) {
+    const entry = meta.entries?.[row.path];
+    if (!entry) continue;
+    entry.chunkIds = (entry.chunkIds || []).filter(id => !removedIds.has(id));
+    if (!entry.chunkIds.length) delete meta.entries[row.path];
+  }
+  writeJson(metaFile, meta);
+  const ledger = JSON.parse(fs.readFileSync(ledgerFile, 'utf8'));
+  const bytes = fs.readFileSync(rvfFile);
+  ledger.stores['ruvnet-brain'] = {
+    ...ledger.stores['ruvnet-brain'],
+    sha256: crypto.createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length,
+    builtUtc: new Date().toISOString(),
+  };
+  writeJson(ledgerFile, ledger);
+  return { removed: removed.length };
+}
+
+function writeJsonLines(file, rows) {
+  fs.writeFileSync(file, `${rows.map((row) => JSON.stringify(row)).join('\n')}\n`);
+}
+
+export function bindCapabilityOnlyGeneration(assetsDir, { builtUtc = new Date().toISOString() } = {}) {
+  const dir = path.resolve(assetsDir);
+  const rvfFile = path.join(dir, `${NAME}.big.rvf`);
+  const metaFile = path.join(dir, `${NAME}.meta.json`);
+  const ledgerFile = path.join(dir, 'RVF-GENERATIONS.json');
+  const embedFile = path.join(dir, `${NAME}.big.rvf.embed.json`);
+  const rvf = fs.readFileSync(rvfFile);
+  const embed = JSON.parse(fs.readFileSync(embedFile, 'utf8'));
+  const meta = JSON.parse(fs.readFileSync(metaFile, 'utf8'));
+  if (embed.model !== MODEL || embed.dimensions !== DIMENSIONS || Object.keys(meta.entries || {}).length !== 1) {
+    throw new Error('rebuilt ruOS store does not match the 768-dim, one-summary contract');
+  }
+  const ledger = JSON.parse(fs.readFileSync(ledgerFile, 'utf8'));
+  if (!ledger || ![1, 2].includes(ledger.schemaVersion) || typeof ledger.stores !== 'object' || !ledger.stores) {
+    throw new Error('seed runtime generation ledger is malformed');
+  }
+  const previous = ledger.stores[NAME] || {};
+  ledger.stores[NAME] = {
+    file: `${NAME}.big.rvf`,
+    sha256: crypto.createHash('sha256').update(rvf).digest('hex'),
+    bytes: rvf.length,
+    model: MODEL,
+    dimensions: DIMENSIONS,
+    sourceCommit: previous.sourceCommit ?? null,
+    builtUtc,
+  };
+  writeJson(ledgerFile, ledger);
+  return ledger.stores[NAME];
+}
+
+export async function refreshCapabilityOnlyStore(assetsDir) {
+  const { dir } = prepareCapabilityOnlyInputs(assetsDir);
+  const selfStore = await pruneCapabilityOnlySelfStore(dir);
+  const script = path.join(ROOT, 'kb/forge-big.mjs');
+  const result = spawnSync(process.execPath, [script, 'both', '--dir', dir, '--name', NAME], {
+    cwd: ROOT, encoding: 'utf8', stdio: 'inherit', env: process.env,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`ruOS capability-only RVF build exited ${result.status}`);
+  return { ...bindCapabilityOnlyGeneration(dir), selfStore };
+}
+
+async function main(argv) {
+  const index = argv.indexOf('--assets');
+  const assetsDir = index >= 0 ? argv[index + 1] : null;
+  if (!assetsDir) throw new Error('Usage: refresh-capability-only-store.mjs --assets <seed-kb-directory>');
+  if (!isCapabilityOnly(NAME)) throw new Error('configured store is not capability-only');
+  const result = await refreshCapabilityOnlyStore(assetsDir);
+  console.log(JSON.stringify({ store: NAME, ...result }));
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  try { await main(process.argv.slice(2)); } catch (error) { console.error(`[capability-store] ${error.message}`); process.exitCode = 1; }
+}

package/scripts/release-qualification-contract.mjs

@@ -17,10 +17,13 @@ export const RELEASE_REQUIREMENTS = Object.freeze({
         "tests/unit/release-identity-invariants.test.mjs",
         "tests/unit/release-transaction.test.mjs",
         "tests/unit/prepublication-evidence.test.mjs",
+        "tests/unit/candidate-host-evidence.test.mjs",
+        "tests/unit/host-install-matrix-concurrency.test.mjs",
         "tests/unit/integration-evidence.test.mjs",
         "tests/unit/qualified-candidate-check.test.mjs",
         "tests/unit/release-qualification.test.mjs",
-        "tests/unit/development-push-boundary.test.mjs"
+        "tests/unit/development-push-boundary.test.mjs",
+        "tests/unit/protected-release-workflow.test.mjs"
       ]
     },
     {
@@ -52,6 +55,13 @@ export const RELEASE_REQUIREMENTS = Object.freeze({
         "tests/unit/nightly-refresh-launcher.test.mjs",
         "tests/unit/nightly-two-run-proof.test.mjs"
       ]
+    },
+    {
+      "id": "ux-hard-acceptance",
+      "reason": "Retry accounting preserves hard UI acceptance failures and chooses only a clean measured attempt",
+      "files": [
+        "tests/unit/ux-render-best-of-n.test.mjs"
+      ]
     }
   ],
   "integration": [

package/scripts/release-vector.mjs

@@ -21,6 +21,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
 
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -276,35 +277,58 @@ export function headSha() {
 /** Strings a non-PASS verdict mechanically bans from release surfaces (ADR-058). */
 export const BANNED_WHEN_DEGRADED = ['healthy', 'proven', 'all pass'];
 
-export async function evaluate(invariants = INVARIANTS, options = {}) {
+export async function evaluate(invariants = INVARIANTS, options = {}, { onInvariantStart, onInvariantComplete } = {}) {
   const lineage = candidateLineage(options.root || ROOT);
   const sha = lineage.sha;
   const results = [];
   for (const inv of invariants) {
+    onInvariantStart?.({ name: inv.name, dimension: inv.dimension });
+    const started = performance.now();
     const r = await inv.detect(options);
-    results.push({ name: inv.name, dimension: inv.dimension, state: r.state, why: r.why, sha });
+    const elapsedMs = Math.max(0, Math.round(performance.now() - started));
+    const result = { name: inv.name, dimension: inv.dimension, state: r.state, why: r.why, sha, elapsedMs };
+    results.push(result);
+    onInvariantComplete?.(result);
   }
   return { sha, lineage, results, verdict: verdictWithLineage(results, lineage) };
 }
 
+/** Map the vector verdict to the process contract: only PASS exits successfully. */
+export function exitCodeForVerdict(verdict) {
+  return verdict === 'PASS' ? 0 : 1;
+}
+
+/** Render either CLI format from one already-evaluated result; rendering never reruns detectors. */
+export function formatVectorOutput(result, { json = false } = {}) {
+  if (json) return JSON.stringify(result, null, 2);
+  const mark = { PASS: '✓', FAIL: '✗', UNKNOWN: '?' };
+  const rows = result.results.map((r) =>
+    `  ${mark[r.state]} ${r.state.padEnd(7)} ${r.dimension.padEnd(3)} ${r.name.padEnd(22)} (${r.elapsedMs ?? '—'}ms) ${r.why}`);
+  const lines = [
+    '',
+    `  release vector @ ${result.sha.slice(0, 7)}`,
+    '',
+    ...rows,
+    `  lineage: tree ${result.lineage.tree.slice(0, 12)} · ${result.lineage.dirty ? 'DIRTY (release-blocking)' : 'clean'}`,
+    '',
+    `  verdict: ${result.verdict}   (vector MINIMUM over ${result.results.length} invariants — never an average)`,
+  ];
+  if (result.verdict !== 'PASS') {
+    lines.push(`  release metadata must read DEGRADED; these strings are banned: ${BANNED_WHEN_DEGRADED.map((s) => `"${s}"`).join(', ')}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
 if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
-  const { sha, lineage, results, verdict } = await evaluate();
+  const timings = process.argv.includes('--timings');
+  const emitTiming = (phase, data) => process.stderr.write(`${JSON.stringify({
+    schema: 'ruvnet-brain.release-vector.timing', phase, ...data,
+  })}\n`);
+  const result = await evaluate(INVARIANTS, {}, timings ? {
+    onInvariantStart: ({ name, dimension }) => emitTiming('start', { name, dimension }),
+    onInvariantComplete: ({ name, dimension, elapsedMs }) => emitTiming('complete', { name, dimension, elapsedMs }),
+  } : {});
   const json = process.argv.includes('--json');
-  if (json) {
-    console.log(JSON.stringify({ sha, lineage, verdict, results }, null, 2));
-  } else {
-    const mark = { PASS: '✓', FAIL: '✗', UNKNOWN: '?' };
-    console.log(`\n  release vector @ ${sha.slice(0, 7)}\n`);
-    for (const r of results) {
-      console.log(`  ${mark[r.state]} ${r.state.padEnd(7)} ${r.dimension.padEnd(3)} ${r.name.padEnd(22)} ${r.why}`);
-    }
-    console.log(`  lineage: tree ${lineage.tree.slice(0, 12)} · ${lineage.dirty ? 'DIRTY (release-blocking)' : 'clean'}`);
-    console.log(`\n  verdict: ${verdict}   (vector MINIMUM over ${results.length} invariants — never an average)`);
-    if (verdict !== 'PASS') {
-      console.log(`  release metadata must read DEGRADED; these strings are banned: ${BANNED_WHEN_DEGRADED.map((s) => `"${s}"`).join(', ')}\n`);
-    } else {
-      console.log('');
-    }
-  }
-  process.exitCode = verdict === 'PASS' ? 0 : 1;
+  console.log(formatVectorOutput(result, { json }));
+  process.exitCode = exitCodeForVerdict(result.verdict);
 }

package/scripts/run-operational-benchmark.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Source-span operational benchmark. Each receipt preserves the exact query, raw customer-path
+// output, citation resolution, oracle match, and latency. It never edits historical eval baselines.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  OPERATIONAL_FIXTURES,
+  gradeOperationalFixture,
+  latencyDistribution,
+  verifyFixtureSourceSupport,
+} from '../evals/operational-benchmark.v2.mjs';
+
+const execFileAsync = promisify(execFile);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
+
+export async function runOperationalBenchmark({ fixtures = OPERATIONAL_FIXTURES, kb = KB, timeoutMs = 240_000 } = {}) {
+  const reader = path.join(kb, 'forge-ask-all.mjs');
+  const verifierPath = path.join(kb, 'verify-citation.mjs');
+  if (!fs.existsSync(reader) || !fs.existsSync(verifierPath)) throw new Error(`RuvNet Brain runtime or verifier missing under ${kb}`);
+  const { verifyGrounding } = await import(pathToFileURL(verifierPath).href);
+  const oracleFiles = new Map();
+  for (const fixture of fixtures) {
+    if (!fixture.expectedFact) continue;
+    const oracleFile = path.join(ROOT, fixture.oraclePath || 'kb/capability-cards.md');
+    if (!fs.existsSync(oracleFile)) throw new Error(`Operational source oracle missing for ${fixture.id}: ${oracleFile}`);
+    oracleFiles.set(oracleFile, true);
+    const oracleText = fs.readFileSync(oracleFile, 'utf8');
+    const normalize = (value) => String(value).replace(/\s+/g, ' ').trim();
+    if (fixture.expectedFact && !normalize(oracleText).includes(normalize(fixture.expectedFact))) {
+      throw new Error(`Source oracle drift for ${fixture.id}: expected fact is absent from ${oracleFile}`);
+    }
+  }
+  const receipts = [];
+  for (const fixture of fixtures) {
+    if (fixture.availability) {
+      receipts.push({ fixtureId: fixture.id, class: fixture.class, query: fixture.query, availability: fixture.availability, grade: { pass: false, reason: 'fixture-not-measurable-with-available-source-oracle' } });
+      process.stderr.write(`UNAVAILABLE ${fixture.id} ${fixture.availability}\n`);
+      continue;
+    }
+    const started = performance.now();
+    let output = '';
+    let stderr = '';
+    let error = null;
+    let processOk = false;
+    let processExitCode = null;
+    try {
+      const args = [reader, '--dir', kb, '--q', fixture.query, '--k', '5'];
+      if (process.env.EVAL_FULL_CORPUS !== '1') args.push('--bounded');
+      const result = await execFileAsync(process.execPath, args, { cwd: kb, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, env: process.env });
+      output = String(result.stdout ?? '');
+      stderr = String(result.stderr ?? '');
+      processOk = true;
+      processExitCode = 0;
+    } catch (caught) {
+      error = caught?.message ?? String(caught);
+      output = String(caught?.stdout ?? '');
+      stderr = String(caught?.stderr ?? '');
+      processExitCode = Number.isInteger(caught?.code) ? caught.code : null;
+    }
+    const elapsedMs = Math.round(performance.now() - started);
+    const verification = await verifyGrounding(output, kb);
+    const sourceSupport = processOk ? await verifyFixtureSourceSupport(fixture, verification, kb) : null;
+    const grade = gradeOperationalFixture(fixture, { output, verification, sourceSupport, processOk });
+    receipts.push({
+      fixtureId: fixture.id,
+      class: fixture.class,
+      query: fixture.query,
+      expectedRepos: fixture.expectedRepos,
+      expectedFact: fixture.expectedFact,
+      elapsedMs,
+      processOk,
+      processExitCode,
+      error,
+      stderr,
+      verification,
+      sourceSupport,
+      grade,
+      rawOutput: output,
+    });
+    process.stderr.write(`${grade.pass ? 'PASS' : 'FAIL'} ${fixture.id} ${elapsedMs}ms\n`);
+  }
+  const classes = Object.fromEntries([...new Set(fixtures.map((fixture) => fixture.class))].map((name) => [
+    name,
+    {
+      pass: receipts.filter((row) => row.class === name && !row.availability && row.grade.pass).length,
+      n: receipts.filter((row) => row.class === name && !row.availability).length,
+      unavailable: receipts.filter((row) => row.class === name && row.availability).length,
+      latency: latencyDistribution(receipts.filter((row) => row.class === name && !row.availability).map((row) => row.elapsedMs)),
+    },
+  ]));
+  return {
+    schema: 'ruvnet-brain-operational-benchmark/v2',
+    generatedAt: new Date().toISOString(),
+    runtime: {
+      kb: path.resolve(kb),
+      nodeExecutable: process.execPath,
+      nodeVersion: process.version,
+      readerSha256: await hashFile(reader),
+      verifierSha256: await hashFile(verifierPath),
+      fixtureSha256: await hashFile(path.join(ROOT, 'evals', 'operational-benchmark.v2.mjs')),
+      oracleSha256: Object.fromEntries(await Promise.all([...oracleFiles.keys()].map(async (file) => [path.relative(ROOT, file), await hashFile(file)]))),
+      sourceManifestSha256: await hashExistingFiles(kb, ['SOURCE.json', 'RVF-GENERATIONS.json', 'PUBLIC-RVF-GENERATIONS.json']),
+    },
+    evaluationConfig: { lane: process.env.EVAL_FULL_CORPUS === '1' ? 'full-corpus' : 'bounded', k: 5, timeoutMs, sequential: true },
+    identityScope: 'Entry-point, verifier, checked manifests, capability-card oracle, and each evidence-bearing passage store are SHA-256 bound. This is not a signed release archive or a hash of every transitive package/model input.',
+    claimBoundary: { sourceSupportedRetrievalUtility: 'measured', generatedAnswerUsefulness: 'UNKNOWN; this retrieval tool does not provide a generated answer to grade' },
+    classes,
+    passed: receipts.filter((row) => row.grade.pass).length,
+    total: receipts.filter((row) => !row.availability).length,
+    unavailable: receipts.filter((row) => row.availability).map(({ fixtureId, availability }) => ({ fixtureId, availability })),
+    receipts,
+  };
+}
+
+async function hashFile(file) {
+  const { createHash } = await import('node:crypto');
+  return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+async function hashExistingFiles(dir, names) {
+  const result = {};
+  for (const name of names) {
+    const file = path.join(dir, name);
+    if (fs.existsSync(file)) result[name] = await hashFile(file);
+  }
+  return result;
+}
+
+async function main() {
+  const classIndex = process.argv.indexOf('--class');
+  const selectedClass = classIndex >= 0 ? process.argv[classIndex + 1] : null;
+  const fixtures = selectedClass ? OPERATIONAL_FIXTURES.filter((fixture) => fixture.class === selectedClass) : OPERATIONAL_FIXTURES;
+  if (!fixtures.length) throw new Error(`No operational fixtures for class ${selectedClass}`);
+  const report = await runOperationalBenchmark({ fixtures });
+  const outDir = path.join(ROOT, 'evals', 'operational-runs');
+  fs.mkdirSync(outDir, { recursive: true });
+  const out = path.join(outDir, `${report.generatedAt.replace(/[:.]/g, '-')}.json`);
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`);
+  console.log(JSON.stringify({ pass: report.passed === report.total && report.unavailable.length === 0, unavailable: report.unavailable.length, passed: report.passed, total: report.total, classes: report.classes, receipt: out }, null, 2));
+  if (report.passed !== report.total || report.unavailable.length) process.exitCode = 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(error.stack || error.message); process.exitCode = 2; });
+}