ruvnet-brain 4.3.25 → 4.3.27

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-transaction-provider.mjs

@@ -21,6 +21,11 @@ const json = (name, args, options) => JSON.parse(command(name, args, options));
 // night a corpus round shipped. Every question this provider asks is about the CODE generation, so
 // it must resolve the latest CODE release rather than read a pointer that now answers differently.
 const latestCodeTag = () => latestCodeReleaseTag(json('gh', ['api', `repos/${REPO}/releases?per_page=30`]));
+// Two DIFFERENT questions, deliberately: latestCodeTag() is "which CODE generation is newest" (a
+// corpus generation may hold the pointer — designed steady state); githubPointerTag() is "what does
+// GitHub's releases/latest actually point at right now". The publish-github-nonlatest gate needs the
+// second and was reading the first, which made it unsatisfiable for every freshly published release.
+const githubPointerTag = () => maybe(() => json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name, null);
 const maybe = (callback, fallback = null) => {
   try { return callback(); } catch { return fallback; }
 };
@@ -79,14 +84,26 @@ const sha256File = (file) => {
   return hash.digest('hex');
 };
 const assetDigest = (asset) => withTempAsset(asset, sha256File);
+// 4.3.25 run 35056636514: `npm publish` succeeded at ~04:47:31Z and the registry first showed the
+// version at 04:53:40Z (time.modified) — roughly six minutes. The poll gave up at 156s, the job
+// reported FAILURE, and an already-published release was left half-promoted with npm and GitHub
+// naming different generations (the exact #77 split). The action was never the problem; the
+// deadline was shorter than npm's propagation for this package. Ten minutes covers the observed
+// ~6 with margin; the env overrides remain for a runner that knows better.
 const OBSERVATION_POLICY = {
-  maxElapsedMs: Number(process.env.RUVNET_NPM_VISIBILITY_TIMEOUT_MS || 180_000),
-  maxAttempts: Number(process.env.RUVNET_NPM_VISIBILITY_ATTEMPTS || 14),
+  maxElapsedMs: Number(process.env.RUVNET_NPM_VISIBILITY_TIMEOUT_MS || 600_000),
+  maxAttempts: Number(process.env.RUVNET_NPM_VISIBILITY_ATTEMPTS || 40),
   initialDelayMs: 1_000,
   maxDelayMs: 15_000,
   multiplier: 1.8,
   jitter: (delay) => Math.floor(Math.random() * Math.min(1_000, delay * 0.2)),
 };
+// The one command in this file that mutates a public channel gets its stderr in the job log and a
+// timeout sized for a real registry upload. command()'s defaults — stderr piped and dropped, 30s —
+// meant 4.3.25's first run left NO diagnostic between "stage-npm" and the deadline error, and a slow
+// registry would have killed a legitimate publish mid-upload. Named, so the publish call stays one
+// pinnable line for tests/unit/release-lineage + publication-receipt-wiring (one publisher, one tag).
+const PUBLISH_COMMAND_OPTIONS = Object.freeze({ stdio: ['ignore', 'pipe', 'inherit'], timeout: 600_000 });
 
 export function selectCurrentReleaseBytes({ remoteBytes, localBytes, generatedBytes, identity }) {
   const bytes = remoteBytes || localBytes || generatedBytes;
@@ -263,6 +280,7 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
       try {
         const release = draft?.id ? hydratedRelease(releaseById(draft.id)) : null;
         const latestTag = latestCodeTag();
+        const pointerTag = githubPointerTag();
         const candidate = maybe(() => json('npm', ['view', `${PACKAGE}@candidate-v${identity.version}`, '--json']), null);
         const exactVersion = maybe(() => json('npm', ['view', `${PACKAGE}@${identity.version}`, '--json']), null);
         const latestVersion = command('npm', ['view', `${PACKAGE}@latest`, 'version']);
@@ -295,8 +313,10 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
             published: release.draft === false,
             latest: latestTag === identity.tag,
             latestTag,
+            // What releases/latest actually points at — distinct from `latest` (code recency) above.
+            pointerTag,
             assetsExact: assetsExactFor(release, identity, forceAssets),
-          } : { tag: null, sha: null, draft: false, published: false, latest: false, assetsExact: false },
+          } : { tag: null, sha: null, draft: false, published: false, latest: false, pointerTag, assetsExact: false },
           publicReceiptExact,
           publicHostsExact,
         };
@@ -400,7 +420,7 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
         command('npm', ['dist-tag', 'add', `${PACKAGE}@${identity.version}`, `candidate-v${identity.version}`]);
         return;
       }
-      command('npm', ['publish', packagePath, '--tag', `candidate-v${identity.version}`]);
+      command('npm', ['publish', packagePath, '--tag', `candidate-v${identity.version}`], PUBLISH_COMMAND_OPTIONS);
     },
 
     async observeNpmCandidate(identity) {
@@ -437,7 +457,7 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
       // legitimately holding `releases/latest` is NOT that — it is the designed steady state between
       // code releases — so the comparison is made against the latest CODE release, and the pointer's
       // own kind is recorded rather than treated as a conflict.
-      const pointer = json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name;
+      const pointer = githubPointerTag();
       const current = latestCodeTag();
       if (current !== expectedPrior && current !== identity.tag) {
         throw new Error(`refusing GitHub promotion: latest code release is ${current}, expected ${expectedPrior}`);

package/scripts/release-transaction.mjs

@@ -194,6 +194,25 @@ const npmCandidateExact = (snapshot, identity) => snapshot?.npm?.candidateVersio
 const npmLatestIsB = (snapshot, identity) => snapshot?.npm?.latestVersion === identity.version;
 const githubIsB = (snapshot, identity) => snapshot?.github?.sha === identity.candidateSha
   && snapshot?.github?.tag === identity.tag;
+// TWO DIFFERENT QUESTIONS ABOUT "LATEST", ANSWERED BY TWO DIFFERENT FIELDS (4.3.25, 2026-09-16).
+//
+// `snapshot.github.latest` is "is this the newest CODE release" — observeGithub derives it from
+// latestCodeReleaseTag(), deliberately, because per ADR-086 S1 a corpus generation may legitimately
+// hold GitHub's releases/latest pointer and a code release must not observe itself as demoted.
+// `snapshot.github.pointerTag` is what releases/latest actually points at.
+//
+// Every promotion, recovery, verification and abort check in this file wants the SECOND question:
+// "has the pointer been moved to B yet". Ten sites read the first. A freshly published code release
+// is ALWAYS the newest code release, so `!latest` was unsatisfiable (publish gate, resume clause —
+// the transaction wedged at github-promote-intent), `latest` was trivially true (promotion looked
+// already done, the pointer never moved, converge and finalize passed with it unmoved), and abort
+// refused because "latest" had moved. Ask the pointer. Snapshots without one (recorded receipts,
+// older providers) fall back to code recency so history stays interpretable.
+const githubPointerIsB = (snapshot, identity) => (snapshot?.github?.pointerTag !== undefined
+  ? snapshot.github.pointerTag === identity.tag
+  : snapshot?.github?.latest === true);
+const githubPointerTag = (snapshot) => (snapshot?.github?.pointerTag !== undefined
+  ? snapshot.github.pointerTag : snapshot?.github?.latestTag);
 
 /**
  * Pure, total next-action selector. Receipt history is an audit chain, never permission to skip a
@@ -206,7 +225,7 @@ export function reduceReleaseState({ lastReceipt, snapshot, identity, prior }) {
   const npmB = npmLatestIsB(snapshot, identity);
   const githubB = githubIsB(snapshot, identity);
   const githubPublished = githubB && snapshot.github?.published === true;
-  const githubLatest = githubPublished && snapshot.github?.latest === true;
+  const githubLatest = githubPublished && githubPointerIsB(snapshot, identity);
 
   if (snapshot.npm?.candidateVersion === identity.version && snapshot.npm?.candidateIntegrity
     && snapshot.npm.candidateIntegrity !== identity.packageIntegrity) {
@@ -338,8 +357,11 @@ export async function runReleaseTransaction({ identity, assets, adapter, private
       await transition('prepared', { recovered: true });
       continue;
     }
+    // 4.3.25 run 35109036116: run 2 died after writing github-promote-intent, run 3 found the draft
+    // published, the reducer asked for promote-npm — not a legal edge from here. This clause was the
+    // only legal exit and its `!latest` was unsatisfiable. Wedged.
     if (current.state === 'github-promote-intent' && githubIsB(snapshot, identity)
-      && snapshot.github?.published && !snapshot.github?.latest) {
+      && snapshot.github?.published && !githubPointerIsB(snapshot, identity)) {
       await transition('github-promoted-nonlatest', { github: snapshot.github, recovered: true });
       continue;
     }
@@ -348,7 +370,7 @@ export async function runReleaseTransaction({ identity, assets, adapter, private
       continue;
     }
     if (current.state === 'github-latest-intent' && npmLatestIsB(snapshot, identity)
-      && githubIsB(snapshot, identity) && snapshot.github?.latest) {
+      && githubIsB(snapshot, identity) && githubPointerIsB(snapshot, identity)) {
       await transition('defaults-promoted', { npm: snapshot.npm, github: snapshot.github, recovered: true });
       continue;
     }
@@ -357,7 +379,7 @@ export async function runReleaseTransaction({ identity, assets, adapter, private
       throw new Error('npm compensation recovered; resume the same transaction');
     }
     if (current.state === 'finalize-intent' && npmCandidateExact(snapshot, identity) && npmLatestIsB(snapshot, identity)
-      && githubIsB(snapshot, identity) && snapshot.github?.published && snapshot.github?.latest
+      && githubIsB(snapshot, identity) && snapshot.github?.published && githubPointerIsB(snapshot, identity)
       && snapshot.github?.assetsExact) {
       return append('channels-converged', { verdict: 'PUBLISHED_NOT_VERIFIED', recovered: true,
         npm: snapshot.npm, github: snapshot.github });
@@ -425,7 +447,10 @@ export async function runReleaseTransaction({ identity, assets, adapter, private
       await transition('github-promote-intent');
       await adapter.publishDraftNonLatest(draft, identity);
       const observed = await adapter.observeSnapshot(identity, draft);
-      if (!(githubIsB(observed, identity) && observed.github.published && !observed.github.latest)) {
+      // Published as B, and the POINTER has not moved to B yet — it is promoted later, in
+      // make-github-latest. 4.3.25 run 35057738103 published this correctly and then threw here on
+      // `!latest`, which a just-published code release can never satisfy.
+      if (!(githubIsB(observed, identity) && observed.github.published && !githubPointerIsB(observed, identity))) {
         throw new Error('GitHub non-latest publication not observed');
       }
       await transition('github-promoted-nonlatest', { github: observed.github });
@@ -446,7 +471,7 @@ export async function runReleaseTransaction({ identity, assets, adapter, private
       await transition('github-latest-intent');
       await adapter.makeGithubLatest(draft, identity, prior.githubLatest);
       const observed = await adapter.observeSnapshot(identity, draft);
-      if (!(npmLatestIsB(observed, identity) && observed.github?.latest && githubIsB(observed, identity))) {
+      if (!(npmLatestIsB(observed, identity) && githubPointerIsB(observed, identity) && githubIsB(observed, identity))) {
         throw new Error('provider defaults not jointly observed at candidate B');
       }
       await transition('defaults-promoted', { npm: observed.npm, github: observed.github });
@@ -469,7 +494,7 @@ export async function runReleaseTransaction({ identity, assets, adapter, private
       }
       await transition('finalize-intent');
       const reobserved = await adapter.observeSnapshot(identity, draft, { forceAssets: true });
-      if (!(npmLatestIsB(reobserved, identity) && reobserved.github?.latest && githubIsB(reobserved, identity))) {
+      if (!(npmLatestIsB(reobserved, identity) && githubPointerIsB(reobserved, identity) && githubIsB(reobserved, identity))) {
         throw new Error('provider defaults drifted before channel convergence');
       }
       if (!reobserved.github?.assetsExact || !npmCandidateExact(reobserved, identity)) {
@@ -491,8 +516,12 @@ export async function abortReleaseTransaction({ identity, receipts, reason, auth
   }
   const snapshot = await adapter.observeSnapshot(identity);
   const prior = chain[0]?.observation?.prior;
-  if (!prior || snapshot.npm?.latestVersion === identity.version || snapshot.github?.latest === true
-    || snapshot.npm?.latestVersion !== prior.npmLatest || snapshot.github?.latestTag !== prior.githubLatest) {
+  // "Both defaults still at the captured prior generation" is a question about the npm `latest`
+  // dist-tag and GitHub's releases/latest POINTER. A published-but-not-promoted candidate is the
+  // newest CODE release, so the old `latest === true` / `latestTag !== prior` reads refused to abort
+  // exactly the transaction that most needs aborting: one wedged after publish, before promotion.
+  if (!prior || snapshot.npm?.latestVersion === identity.version || githubPointerIsB(snapshot, identity)
+    || snapshot.npm?.latestVersion !== prior.npmLatest || githubPointerTag(snapshot) !== prior.githubLatest) {
     throw new Error('release abort cannot prove both defaults at captured prior generation');
   }
   const receipt = stateReceipt({
@@ -550,7 +579,7 @@ export async function finalizeReleaseTransaction({
   }
   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
+    || !githubIsB(snapshot, identity) || snapshot.github?.published !== true || !githubPointerIsB(snapshot, identity)
     || snapshot.github?.assetsExact !== true) throw new Error('public channels drifted before install verification');
   const materialized = await adapter.materializePublicVerificationAggregate({ identity, aggregate });
   const aggregateAssetSha256 = crypto.createHash('sha256').update(canonicalJson(aggregate)).digest('hex');
@@ -642,7 +671,7 @@ export async function abandonPublicVerificationTransaction({ identity, expected,
   }
   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
+    || !githubIsB(snapshot, identity) || snapshot.github?.published !== true || !githubPointerIsB(snapshot, identity)
     || snapshot.github?.assetsExact !== true
     || canonicalJson(snapshot.npm) !== canonicalJson(current.observation.npm)
     || canonicalJson(snapshot.github) !== canonicalJson(current.observation.github)) {

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; });
+}