ruvnet-brain 4.3.26 → 4.3.27

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

package/scripts/run-operational-benchmark.v3.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// v3 validates independently frozen source facts against corpus bytes before running retrieval.
+// Missing corpus facts remain explicit CORPUS_GAP outcomes and block qualification.
+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 } from 'node:url';
+import {
+  OPERATIONAL_FIXTURES_V3,
+  ORACLE_CATALOG,
+  gradeOperationalFixtureV3,
+  matchClaimSlots,
+  preflightOperationalOracle,
+} from '../evals/operational-benchmark.v3.mjs';
+import { verifyGrounding as evaluatorVerifyGrounding } from '../kb/verify-citation.mjs';
+
+const execFileAsync = promisify(execFile);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_KB = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
+const { createHash } = await import('node:crypto');
+const digestBytes = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const hashBytes = async (file) => digestBytes(fs.readFileSync(file));
+const hashIfPresent = async (file) => fs.existsSync(file) ? hashBytes(file) : null;
+
+async function readCatalog(catalog, catalogFile) {
+  if (catalog) return { value: catalog, file: null, sha256: digestBytes(Buffer.from(JSON.stringify(catalog))) };
+  const file = path.resolve(ROOT, catalogFile || ORACLE_CATALOG);
+  try {
+    const bytes = fs.readFileSync(file);
+    return { value: JSON.parse(bytes.toString('utf8')), file, sha256: digestBytes(bytes) };
+  }
+  catch (error) { return { value: null, file, error: error.message }; }
+}
+
+export async function runOperationalBenchmarkV3({ fixtures = OPERATIONAL_FIXTURES_V3, kb = DEFAULT_KB,
+  catalog = null, catalogFile = ORACLE_CATALOG, timeoutMs = 240_000, runQuery = null,
+  verify = null, now = () => new Date().toISOString() } = {}) {
+  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 loaded = await readCatalog(catalog, catalogFile);
+  const catalogSha256AtStart = loaded.sha256 ?? null;
+  // Both baseline and candidate use the evaluator checkout's fixed parser/verifier. The runtime
+  // archive verifier is hashed as runtime metadata, never imported as the grader implementation.
+  const verifier = verify || evaluatorVerifyGrounding;
+  const preflight = loaded.error
+    ? new Map(fixtures.map((fixture) => [fixture.id, { status: 'INVALID_ORACLE', reason: `oracle catalog cannot be read: ${loaded.error}` }]))
+    : await preflightOperationalOracle({ fixtures, catalog: loaded.value, catalogPath: loaded.file, kbDir: kb });
+  const receipts = [];
+  for (const fixture of fixtures) {
+    const oracle = preflight.get(fixture.id) || { status: 'INVALID_ORACLE', reason: 'fixture preflight result is missing' };
+    if (oracle.status !== 'PASS') {
+      const grade = gradeOperationalFixtureV3(fixture, { processOk: true, preflightStatus: oracle.status });
+      receipts.push({ fixtureId: fixture.id, class: fixture.class, query: fixture.query, preflight: oracle,
+        processOk: false, elapsedMs: null, grade });
+      process.stderr.write(`${oracle.status} ${fixture.id} ${oracle.reason}\n`);
+      continue;
+    }
+
+    const started = performance.now();
+    let output = '';
+    let stderr = '';
+    let error = null;
+    let processExitCode = null;
+    let processOk = false;
+    try {
+      const result = runQuery
+        ? await runQuery(fixture, { kb, timeoutMs })
+        : await execFileAsync(process.execPath, [reader, '--dir', kb, '--q', fixture.query, '--k', '5',
+          ...(process.env.EVAL_FULL_CORPUS === '1' ? [] : ['--bounded'])],
+        { cwd: kb, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, env: process.env });
+      output = String(result?.stdout ?? '');
+      stderr = String(result?.stderr ?? '');
+      processOk = result?.code === undefined ? result?.status === undefined || result.status === 0 : result.code === 0;
+      processExitCode = result?.code ?? result?.status ?? 0;
+      if (!processOk) error = 'retrieval process returned a nonzero status';
+    } 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 = processOk ? await verifier(output, kb) : null;
+    const sourceSupport = fixture.class === 'negative' || fixture.class === 'ambiguity'
+      ? null : matchClaimSlots(oracle, verification);
+    const grade = gradeOperationalFixtureV3(fixture, { output, verification, sourceSupport,
+      processOk, preflightStatus: oracle.status });
+    receipts.push({ fixtureId: fixture.id, class: fixture.class, query: fixture.query,
+      preflight: { status: oracle.status, resolvedSlots: oracle.resolvedSlots?.map((slot) => ({
+        id: slot.id, alternatives: slot.alternatives.map(({ repo, path: sourcePath, passageSha256,
+          store, storeSha256, sourceRowsByStore }) => ({ repo, path: sourcePath, passageSha256, store,
+          storeSha256, sourceStores: sourceRowsByStore.map(({ store: sourceStore, storeSha256: sourceStoreSha256 }) =>
+            ({ store: sourceStore, storeSha256: sourceStoreSha256 })) })),
+      })) ?? [] }, elapsedMs, processOk, processExitCode, error, stderr, verification, sourceSupport,
+      grade, rawOutput: output });
+    process.stderr.write(`${grade.status} ${fixture.id} ${elapsedMs}ms\n`);
+  }
+
+  // Close the receipt over the inputs after replay as well as before it. If any pinned corpus
+  // bytes or oracle catalog moved mid-run, demote every affected row so a race cannot pass.
+  const corpusChanged = loaded.value?.corpus && (
+    await hashIfPresent(path.join(kb, 'ARCHIVE-MANIFEST.json')) !== loaded.value.corpus.archiveManifestSha256
+    || await hashIfPresent(path.join(kb, 'SOURCE.json')) !== loaded.value.corpus.sourceManifestSha256);
+  const oracleChanged = loaded.file && await hashIfPresent(loaded.file) !== catalogSha256AtStart;
+  if (corpusChanged || oracleChanged) {
+    for (const row of receipts) {
+      if (row.preflight?.status !== 'PASS') continue;
+      row.preflight = { status: corpusChanged ? 'CORPUS_GAP' : 'INVALID_ORACLE',
+        reason: corpusChanged ? 'pinned corpus identity changed during replay' : 'oracle catalog bytes changed during replay' };
+      row.grade = { pass: false, status: row.preflight.status, reason: row.preflight.reason };
+    }
+  }
+  const storeIdentities = new Map();
+  for (const row of receipts) {
+    for (const slot of row.preflight?.resolvedSlots ?? []) {
+      for (const alt of slot.alternatives ?? []) {
+        storeIdentities.set(alt.store, alt.storeSha256);
+        for (const sourceStore of alt.sourceStores ?? []) storeIdentities.set(sourceStore.store, sourceStore.storeSha256);
+      }
+    }
+  }
+  for (const [store, expectedSha256] of storeIdentities) {
+    const actual = await hashIfPresent(path.join(kb, store));
+    if (actual === expectedSha256) continue;
+    for (const row of receipts) {
+      const bound = (row.preflight?.resolvedSlots ?? []).some((slot) => slot.alternatives?.some((alt) =>
+        alt.store === store || alt.sourceStores?.some((sourceStore) => sourceStore.store === store)));
+      if (!bound || row.preflight.status !== 'PASS') continue;
+      row.preflight = { status: 'CORPUS_GAP', reason: `source passage store ${store} changed or disappeared during replay` };
+      row.grade = { pass: false, status: 'CORPUS_GAP', reason: row.preflight.reason };
+    }
+  }
+
+  const classes = Object.fromEntries([...new Set(fixtures.map(({ class: fixtureClass }) => fixtureClass))].map((name) => {
+    const rows = receipts.filter((row) => row.class === name);
+    const measured = rows.filter((row) => row.preflight?.status === 'PASS');
+    const latencies = measured.filter((row) => Number.isFinite(row.elapsedMs)).map((row) => row.elapsedMs).sort((a, b) => a - b);
+    const percentile = (f) => latencies.length ? latencies[Math.max(0, Math.ceil(latencies.length * f) - 1)] : null;
+    return [name, { pass: measured.filter((row) => row.grade.pass).length, n: measured.length,
+      corpusGap: rows.filter((row) => row.preflight?.status === 'CORPUS_GAP').length,
+      invalidOracle: rows.filter((row) => row.preflight?.status === 'INVALID_ORACLE').length,
+      latency: { n: latencies.length, p50Ms: percentile(.5), p95Ms: percentile(.95), p99Ms: percentile(.99), maxMs: latencies.at(-1) ?? null } }];
+  }));
+  const [readerSha256, runtimeVerifierSha256, evaluatorParserSha256, archiveManifestSha256, sourceManifestSha256,
+    runnerSha256, graderSha256, querySetSha256, oracleCatalogSha256] = await Promise.all([
+    hashBytes(reader), hashBytes(verifierPath), hashBytes(path.join(ROOT, 'kb/verify-citation.mjs')),
+    hashIfPresent(path.join(kb, 'ARCHIVE-MANIFEST.json')),
+    hashIfPresent(path.join(kb, 'SOURCE.json')),
+    hashBytes(fileURLToPath(import.meta.url)), hashBytes(path.join(ROOT, 'evals/operational-benchmark.v3.mjs')),
+    Promise.resolve(digestBytes(Buffer.from(JSON.stringify(fixtures)))),
+    Promise.resolve(catalogSha256AtStart),
+  ]);
+  const measured = receipts.filter((row) => row.preflight?.status === 'PASS');
+  const unavailable = receipts.filter((row) => row.preflight?.status === 'CORPUS_GAP')
+    .map(({ fixtureId, preflight: result }) => ({ fixtureId, reason: result.reason }));
+  const invalidOracle = receipts.filter((row) => row.preflight?.status === 'INVALID_ORACLE')
+    .map(({ fixtureId, preflight: result }) => ({ fixtureId, reason: result.reason }));
+  return {
+    schema: 'ruvnet-brain-operational-benchmark/v3', generatedAt: now(),
+    runtime: { kb: path.resolve(kb), nodeExecutable: process.execPath, nodeVersion: process.version,
+      readerSha256, runtimeVerifierSha256, evaluatorParserSha256, archiveManifestSha256, sourceManifestSha256,
+      runnerSha256, graderSha256, querySetSha256, oracleCatalogSha256 },
+    evaluationConfig: { lane: process.env.EVAL_FULL_CORPUS === '1' ? 'full-corpus' : 'bounded',
+      k: 5, timeoutMs, sequential: true, preflightBeforeSearch: true },
+    claimBoundary: { sourceSupportedRetrieval: 'measured', generatedAnswerUsefulness: 'UNKNOWN; this is a retrieval tool evaluation' },
+    classes, passed: measured.filter((row) => row.grade.pass).length,
+    measured: measured.length, total: fixtures.length, corpusGaps: unavailable,
+    invalidOracles: invalidOracle,
+    qualificationPass: measured.length === fixtures.length && invalidOracle.length === 0
+      && unavailable.length === 0 && measured.every((row) => row.grade.pass),
+    receipts,
+  };
+}
+
+async function main() {
+  const kb = process.env.RUVNET_BRAIN_KB || DEFAULT_KB;
+  const report = await runOperationalBenchmarkV3({ fixtures: OPERATIONAL_FIXTURES_V3, kb });
+  const outDir = path.join(ROOT, 'evals', 'operational-runs');
+  fs.mkdirSync(outDir, { recursive: true });
+  const out = path.join(outDir, `v3-${report.generatedAt.replace(/[:.]/g, '-')}.json`);
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`);
+  console.log(JSON.stringify({ qualificationPass: report.qualificationPass, measured: report.measured,
+    total: report.total, corpusGaps: report.corpusGaps.length, invalidOracles: report.invalidOracles.length,
+    classes: report.classes, receipt: out }, null, 2));
+  if (!report.qualificationPass) 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; });
+}

package/scripts/self-update.mjs

@@ -167,6 +167,8 @@ for (const r of inScope) {
   else if (built === 'unknown') action = live ? 'rebuild (changed)' : 'unverified (probe failed)';
   else if (live === null) action = 'unverified (probe failed)';
   else if (live !== built) action = 'rebuild (changed)';
+  // The curated capability summary can change without a change to upstream code.
+  if (r.name === 'cognitum-ruos' && live) action = 'rebuild (changed)';
   plan.push({ name: r.name, owner: r.owner, repo: r.repo, tier: r.tier, built: built?.slice(0, 12) || '—', live: live?.slice(0, 12) || '?', action });
 }
 if (inScope.length > 0 && probeFailures * 2 >= inScope.length) {

package/scripts/source-coverage.mjs

@@ -215,6 +215,9 @@ export function canonicalGistRows(rows = []) {
     id: gist?.id,
     updated_at: gist?.updated_at ?? null,
     html_url: gist?.html_url,
+    // Preserve GitHub's top-level completeness indicator. `files.truncated` is a different
+    // per-file content flag; neither omission nor a missing value means the inventory is complete.
+    ...(Object.hasOwn(gist || {}, 'truncated') ? { truncated: gist.truncated } : {}),
     files: Object.fromEntries(Object.entries(gist?.files || {}).sort(([a], [b]) => a.localeCompare(b))
       .map(([key, file]) => [key, {
         filename: file?.filename,
@@ -409,6 +412,7 @@ export function classifyGist(gist, evidence) {
   let status = 'CURRENT';
   const reasons = [];
   if (!evidence.rvfPresent) { status = 'MISSING'; reasons.push('ruv-gists RVF is absent'); }
+  else if (gist.truncated !== false) { status = 'UNVERIFIED'; reasons.push('GitHub gist file inventory is truncated or its completeness flag is unknown'); }
   else if (!evidence.receipt || !source || !version) { status = 'UNVERIFIED'; reasons.push('per-gist source receipt is absent'); }
   else if (!evidence.bytesVerified) { status = 'FAILED'; reasons.push('ruv-gists RVF bytes do not match the generation receipt'); }
   else if (!evidence.passagesBound) { status = 'FAILED'; reasons.push('gist passages do not match the source receipt'); }
@@ -421,7 +425,8 @@ export function classifyGist(gist, evidence) {
     name: Object.values(gist.files || {})[0]?.filename || gist.id,
     url: gist.html_url,
     disposition: 'eligible',
-    upstream: { sha: version, updatedAt: gist.updated_at, fileCount: filenames.length, files: filenames },
+    upstream: { sha: version, updatedAt: gist.updated_at, truncated: gist.truncated ?? null,
+      fileCount: filenames.length, files: filenames },
     artifact: { store: 'ruv-gists', sourceCommit: source?.versionSha || null, ingestedAt: source?.ingestedAt || ingestedAt,
       contentDigest: source?.contentDigest || null, fileCount: source?.files?.length || null,
       rvfSha256: evidence.receipt?.sha256 || null, bytesVerified: evidence.bytesVerified },

package/scripts/sync-version.mjs

@@ -33,6 +33,14 @@ export function writeLockVersion(s, version) {
   return `${JSON.stringify(doc, null, 2)}\n`;
 }
 
+export function readExplainerBadgeVersion(s) {
+  return s.match(/&middot;\s*v(\d+\.\d+\.\d+(?:-[\w.-]+)?)(?=\s*(?:&middot;|<))/)?.[1] ?? null;
+}
+
+export function writeExplainerBadgeVersion(s, version) {
+  return s.replace(/(&middot;\s*v)\d+\.\d+\.\d+(?:-[\w.-]+)?/, `$1${version}`);
+}
+
 // Each target: a file, a regex to find the version-bearing line, and the corrected line.
 const targets = [
   { // Codex plugin manifest — same product, same release train as the Claude manifest
@@ -71,12 +79,12 @@ const targets = [
     file: 'explainer/index.html',
     get: (s) => {
       const ld = s.match(/"softwareVersion"\s*:\s*"([^"]+)"/)?.[1] ?? null;
-      const badge = s.match(/&middot;\s*v([0-9][^\s<]*)</)?.[1] ?? null;
+      const badge = readExplainerBadgeVersion(s);
       return ld === badge ? ld : `mixed(${ld}, ${badge})`;
     },
     set: (s) => s
       .replace(/("softwareVersion"\s*:\s*)"[^"]+"/, `$1"${V}"`)
-      .replace(/(&middot;\s*v)[0-9][^\s<]*</, `$1${V}<`),
+      .replace(/&middot;\s*v\d+\.\d+\.\d+(?:-[\w.-]+)?/, (label) => writeExplainerBadgeVersion(label, V)),
   },
 ];