ruvnet-brain 4.3.35 → 4.3.36

package/scripts/oracle/repo-recall.mjs

@@ -34,6 +34,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { extractZip } from '../../kb/zip-extract.mjs';
+import { validateCoverageLedger } from '../coverage-integrity.mjs';
+import { retiredFixtureStores } from '../fixture-denominator.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
@@ -153,30 +155,50 @@ export function scoreQuestion({ store, expectedPath, results }) {
   };
 }
 
-/** Roll per-question rows into the counts the predicates are evaluated on. */
+/**
+ * Roll per-question rows into the counts the predicates are evaluated on.
+ *
+ * ADR-0091 D7.4: a row marked `retired: true` (its repository has no row at all in a complete sealed
+ * coverage observation) is excluded from EVERY count, and `retired` is added -- but only when it is
+ * non-zero, so a report with no retirements is byte-for-byte the pre-D7 shape and readable in both
+ * directions. An older reader of a report WITH retirements re-derives different totals and fails
+ * closed, which is the intended behavior (D4's pre-download check turns that into a seed fallback).
+ */
 export function tally(rows) {
-  const completed = rows.filter((r) => !r.error).length;
+  const live = rows.filter((r) => r.retired !== true);
+  const retired = rows.length - live.length;
+  const completed = live.filter((r) => !r.error).length;
   return {
-    questions: rows.length,
+    questions: live.length,
     completed,
-    errors: rows.length - completed,
-    repoCoverage: rows.filter((r) => r.repoCovered).length,
-    hitTop1: rows.filter((r) => r.exactFileRank === 1).length,
-    hitTop5: rows.filter((r) => r.exactFileRank != null && r.exactFileRank <= DEFAULT_K).length,
+    errors: live.length - completed,
+    repoCoverage: live.filter((r) => r.repoCovered).length,
+    hitTop1: live.filter((r) => r.exactFileRank === 1).length,
+    hitTop5: live.filter((r) => r.exactFileRank != null && r.exactFileRank <= DEFAULT_K).length,
+    ...(retired > 0 ? { retired } : {}),
   };
 }
 
+const FLOOR_FAILURE = /below the accepted floor/;
+/** ADR-0091 D7.6: the integrity failures. A floor miss is recorded in the report, never enforced. */
+export const blockingFailures = (failures) => failures.filter((failure) => !FLOOR_FAILURE.test(failure));
+
 /**
  * EVERY blocking predicate, in one place, evaluated over counts alone. Returns the full failure
  * list rather than the first failure, so one run tells an operator everything that is wrong.
+ * The denominator is the frozen fixture minus retired questions (ADR-0091 D7.4) -- the SAME exclusion
+ * tally applies, or the totals re-derivation and the gate would disagree.
  */
 export function evaluateGate({ totals, floorValue, fixtureCount }) {
   const failures = [];
-  if (totals.questions !== fixtureCount) failures.push(`asked ${totals.questions} of ${fixtureCount} frozen questions`);
+  const retired = Number.isSafeInteger(totals.retired) && totals.retired > 0 ? totals.retired : 0;
+  const expected = fixtureCount - retired;
+  const of = retired ? `${expected} (${fixtureCount} frozen, ${retired} retired)` : `${fixtureCount}`;
+  if (totals.questions !== expected) failures.push(`asked ${totals.questions} of ${of} frozen questions`);
   if (totals.errors !== 0) failures.push(`${totals.errors} question(s) failed to complete`);
-  if (totals.completed !== fixtureCount) failures.push(`${totals.completed} of ${fixtureCount} questions completed`);
-  if (totals.repoCoverage !== fixtureCount) {
-    failures.push(`${fixtureCount - totals.repoCoverage} repository(ies) returned nothing of their own`);
+  if (totals.completed !== expected) failures.push(`${totals.completed} of ${of} questions completed`);
+  if (totals.repoCoverage !== expected) {
+    failures.push(`${expected - totals.repoCoverage} repository(ies) returned nothing of their own`);
   }
   if (totals.hitTop5 < floorValue) {
     failures.push(`exact-file Hit@5 regressed to ${totals.hitTop5}, below the accepted floor of ${floorValue}`);
@@ -184,7 +206,73 @@ export function evaluateGate({ totals, floorValue, fixtureCount }) {
   return { verdict: failures.length === 0 ? 'PASS' : 'FAIL', failures };
 }
 
-export function validateRecallReport({ report, archive, expectedFixtureSha256 = null, floorValue = null, floorFile = null } = {}) {
+function parseSealedCoverage(bytes, label) {
+  let coverage;
+  try { coverage = JSON.parse(Buffer.from(bytes).toString('utf8')); }
+  catch (error) { fail(`${label} is unreadable (${error.message})`); }
+  const checked = validateCoverageLedger(coverage);
+  if (coverage?.kind !== 'ruvnet-brain-corpus-coverage' || !checked.valid) {
+    fail(`${label} is not a valid sealed ruvnet-brain-corpus-coverage ledger (${checked.failures.join('; ') || coverage?.kind})`);
+  }
+  return coverage;
+}
+
+const sortedLower = (values) => [...new Set(values.map((value) => String(value).toLowerCase()))].sort();
+
+/**
+ * ADR-0091 D7.3 -- readers verify, never trust. The retired set a report CLAIMS (its `retirement`
+ * block and the rows it marks `retired: true`) is recomputed here, independently, from coverage bytes
+ * the reader obtained itself, through the one shared retirement function (scripts/fixture-
+ * denominator.mjs, also used by the release canary). Returns the failures; empty means consistent.
+ *
+ * A reader with no verifiable coverage treats ANY claimed retirement as invalid, and every claimed
+ * store must be retired by the coverage the claim names. The check is claimed ⊆ recomputed, not
+ * equality: retirement only ever REMOVES a question from the denominator, so the unsafe direction is
+ * an over-claim (hiding an unanswered question). An under-claim keeps a question in the denominator,
+ * which can only make the gate stricter. A report that claims nothing needs no coverage at all, so
+ * the pre-D7 path (every report today) reads exactly as it did.
+ */
+export function retirementFailures({ report, coverageBytes = null, fixtureStores = null }) {
+  const rows = Array.isArray(report?.rows) ? report.rows : [];
+  const markedRows = rows.filter((row) => row?.retired === true);
+  const claim = report?.retirement;
+  const claims = claim !== undefined || markedRows.length > 0 || report?.totals?.retired !== undefined;
+  if (!claims) return [];
+  if (!claim || typeof claim !== 'object' || !HEX64.test(String(claim.coverageSha256 || ''))
+    || !Array.isArray(claim.stores) || !claim.stores.length) {
+    return ['repo-recall report marks questions retired without a well-formed retirement block'];
+  }
+  const failures = [];
+  const claimed = sortedLower(claim.stores);
+  if (JSON.stringify(claimed) !== JSON.stringify(sortedLower(markedRows.map((row) => row.store)))) {
+    failures.push('repo-recall report\'s retirement block does not name exactly the rows it marks retired');
+  }
+  // A retired question was never asked, so it can carry no evidence of an answer.
+  if (markedRows.some((row) => row.repoCovered !== false || row.exactFileRank !== null || row.error !== undefined)) {
+    failures.push('repo-recall report credits a retired question with an answer');
+  }
+  if (coverageBytes == null) {
+    return [...failures, 'repo-recall report claims retired question(s) but no coverage was supplied to verify them against'];
+  }
+  if (sha256(Buffer.from(coverageBytes)) !== claim.coverageSha256) {
+    return [...failures, 'repo-recall report\'s retirement was measured against different coverage bytes than the ones supplied'];
+  }
+  let coverage;
+  try { coverage = parseSealedCoverage(coverageBytes, 'retirement coverage'); }
+  catch (error) { return [...failures, error.message]; }
+  const recomputed = new Set(retiredFixtureStores({ coverage, fixtureStores: fixtureStores ?? rows.map((row) => row.store) }));
+  const unsupported = claimed.filter((store) => !recomputed.has(store));
+  if (unsupported.length) {
+    failures.push(`repo-recall report claims [${unsupported.join(', ')}] retired, but the coverage it names does not `
+      + 'retire them (they have a repository row, or the enumeration is not complete)');
+  }
+  return failures;
+}
+
+export function validateRecallReport({
+  report, archive, expectedFixtureSha256 = null, floorValue = null, floorFile = null,
+  coverageBytes = null, fixtureStores = null,
+} = {}) {
   const failures = [];
   if (!report || typeof report !== 'object') fail('repo-recall report is not an object');
   if (report.schemaVersion !== RECALL_SCHEMA_VERSION || report.kind !== RECALL_KIND) {
@@ -203,6 +291,7 @@ export function validateRecallReport({ report, archive, expectedFixtureSha256 =
     if (canonical(recomputed) !== canonical(report.totals)) {
       failures.push('repo-recall report totals do not re-derive from its own rows');
     }
+    failures.push(...retirementFailures({ report, coverageBytes, fixtureStores }));
   }
   if (failures.length) fail(`repo-recall report invalid: ${failures.join('; ')}`);
   // NEVER trust the report's own `floor.value`. A report that declares its own bar could declare
@@ -231,14 +320,16 @@ export function validateRecallReport({ report, archive, expectedFixtureSha256 =
   //     quality on the release path is gated by scripts/retrieval-canary.mjs through a real
   //     installed host, which is the instrument that belongs in that role.
   const gate = evaluateGate({ totals: report.totals, floorValue: floor, fixtureCount: report.fixture.questionCount });
-  const blocking = gate.failures.filter((f) => !/below the accepted floor/.test(f));
+  const blocking = blockingFailures(gate.failures);
   report.gate = { blocking: blocking.length > 0, verdict: gate.verdict, failures: gate.failures, enforced: blocking };
   if (blocking.length) fail(`repo-recall integrity FAILED: ${blocking.join('; ')}`);
   return report;
 }
 
 /** Read a detached report beside an archive and enforce the gate. Mirrors readAccuracyReport. */
-export function readRecallReport({ reportFile, archive, expectedFixtureSha256 = null, floorValue = null, floorFile = null } = {}) {
+export function readRecallReport({
+  reportFile, archive, expectedFixtureSha256 = null, floorValue = null, floorFile = null, coverageBytes = null, fixtureStores = null,
+} = {}) {
   const resolved = path.resolve(reportFile || '');
   if (!resolved || !fs.existsSync(resolved)) fail(`detached repo-recall report missing (${resolved || 'no path supplied'})`);
   const stat = fs.lstatSync(resolved);
@@ -246,7 +337,7 @@ export function readRecallReport({ reportFile, archive, expectedFixtureSha256 =
   let parsed;
   try { parsed = JSON.parse(fs.readFileSync(resolved, 'utf8')); }
   catch (error) { fail(`detached repo-recall report unreadable/corrupt (${error.message})`); }
-  const report = validateRecallReport({ report: parsed, archive, expectedFixtureSha256, floorValue, floorFile });
+  const report = validateRecallReport({ report: parsed, archive, expectedFixtureSha256, floorValue, floorFile, coverageBytes, fixtureStores });
   return { identity: { file: path.basename(resolved), sha256: sha256File(resolved), bytes: stat.size }, report };
 }
 
@@ -256,9 +347,22 @@ export function readRecallReport({ reportFile, archive, expectedFixtureSha256 =
  * forge-ask-all.mjs — the exact bytes a customer installs — not the checkout's copy.
  */
 export async function runRepoRecall({
-  kbDir, fixtureFile, floorFile, archive = null, k = DEFAULT_K, searchAll = null, now = () => new Date(),
+  kbDir, fixtureFile, floorFile, archive = null, k = DEFAULT_K, searchAll = null, now = () => new Date(), coverageFile = null,
 } = {}) {
   const fixture = loadFixture(fixtureFile);
+  // ADR-0091 D7.2: a fixture repository with NO row in a complete sealed coverage observation is
+  // retired -- its question is not asked (there is no store to ask) and it leaves the denominator.
+  // The fixture itself is never edited (D7.5): its digest is what seeds and the canary re-verify.
+  let retirement = null;
+  if (coverageFile) {
+    const resolved = path.resolve(coverageFile);
+    if (!fs.existsSync(resolved)) fail(`retirement coverage missing (${resolved})`);
+    const bytes = fs.readFileSync(resolved);
+    const coverage = parseSealedCoverage(bytes, 'retirement coverage');
+    const stores = retiredFixtureStores({ coverage, fixtureStores: fixture.questions.map((q) => q.store) });
+    if (stores.length) retirement = { coverageSha256: sha256(bytes), stores };
+  }
+  const retiredSet = new Set(retirement?.stores || []);
   // Fail-soft, same reason as the reader: a floor recorded against another fixture is a note, not a
   // reason to stop. Nothing here refuses a candidate any more.
   let floor = null; let floorValue = ABSOLUTE_FLOOR;
@@ -291,6 +395,11 @@ export async function runRepoRecall({
 
   const rows = [];
   for (const question of fixture.questions) {
+    if (retiredSet.has(question.store.toLowerCase())) {
+      rows.push({ store: question.store, expectedPath: question.expectedPath, retired: true,
+        repoCovered: false, exactFileRank: null, returnedPaths: [] });
+      continue;
+    }
     try {
       const out = await search({ dir: kbDir, query: question.query, k, repos: [question.store] });
       // searchAll reports a store that could not be OPENED as an "ERR: ..." string in perRepo and
@@ -346,6 +455,8 @@ export async function runRepoRecall({
       questionCount: fixture.questions.length,
       shape: 'exactly one human-written question per repository',
     },
+    // Present ONLY when something retired, so a report with none is the pre-D7 shape byte for byte.
+    ...(retirement ? { retirement } : {}),
     protocol: { entryPoint, k, repositoryScope: 'explicit', scoring: 'exact labeled file path within top-k of results from the requested repository' },
     floor: { value: floorValue, committed: floor?.hitTop5Floor ?? null, absolute: ABSOLUTE_FLOOR, acceptedForRelease: floor?.acceptedForRelease ?? null },
     totals,
@@ -370,7 +481,7 @@ const arg = (argv, name, fallback = null) => {
  * Measure a SEALED archive: extract it, find the store root, and grade that — never the build
  * directory the archive was assembled from. Returns the report bound to the archive's own digest.
  */
-export async function runRepoRecallOnBundle({ bundleFile, fixtureFile, floorFile, k = DEFAULT_K } = {}) {
+export async function runRepoRecallOnBundle({ bundleFile, fixtureFile, floorFile, k = DEFAULT_K, coverageFile = null } = {}) {
   const bundle = path.resolve(bundleFile || '');
   if (!bundle || !fs.existsSync(bundle) || !fs.statSync(bundle).isFile()) {
     fail(`archive missing (${bundle || 'no path supplied'})`);
@@ -389,17 +500,19 @@ export async function runRepoRecallOnBundle({ bundleFile, fixtureFile, floorFile
     };
     walk(tmp);
     if (roots.length !== 1) fail(`expected exactly one ARCHIVE-MANIFEST.json in the archive, found ${roots.length}`);
-    return await runRepoRecall({ kbDir: roots[0], fixtureFile, floorFile, archive, k });
+    return await runRepoRecall({ kbDir: roots[0], fixtureFile, floorFile, archive, k, coverageFile });
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
   }
 }
 
-export async function main(argv = process.argv.slice(2)) {
+// `searchAll` is a test seam only (the CLI never passes it): it lets the exit-code contract be proven
+// without an embedded corpus. Unset, --kb grades the archive's own shipped entry point as always.
+export async function main(argv = process.argv.slice(2), { searchAll = null } = {}) {
   const kbDir = arg(argv, '--kb');
   const bundleFile = arg(argv, '--bundle');
   if (!kbDir && !bundleFile) {
-    process.stderr.write('usage: repo-recall.mjs (--bundle <archive.zip> | --kb <extracted root>) [--out <report.json>] [--fixture <file>] [--floor <file>]\n');
+    process.stderr.write('usage: repo-recall.mjs (--bundle <archive.zip> | --kb <extracted root>) [--out <report.json>] [--fixture <file>] [--floor <file>] [--coverage <sealed coverage>]\n');
     return 64;
   }
   const { report, gate } = bundleFile
@@ -407,11 +520,14 @@ export async function main(argv = process.argv.slice(2)) {
       bundleFile: path.resolve(bundleFile),
       fixtureFile: arg(argv, '--fixture'),
       floorFile: arg(argv, '--floor'),
+      coverageFile: arg(argv, '--coverage'),
     })
     : await runRepoRecall({
       kbDir: path.resolve(kbDir),
+      searchAll,
       fixtureFile: arg(argv, '--fixture'),
       floorFile: arg(argv, '--floor'),
+      coverageFile: arg(argv, '--coverage'),
     });
   const out = arg(argv, '--out') || (bundleFile ? `${path.resolve(bundleFile)}.recall.json` : null);
   if (out) fs.writeFileSync(path.resolve(out), `${JSON.stringify(report, null, 2)}\n`);
@@ -423,10 +539,15 @@ export async function main(argv = process.argv.slice(2)) {
     repositoriesAnswering: `${t.repoCoverage}/${t.questions}`,
     exactFileTop1: `${t.hitTop1}/${t.questions}`,
     exactFileTop5: `${t.hitTop5}/${t.questions}`,
+    ...(t.retired ? { retired: t.retired } : {}),
     floor: report.floor.value,
     failures: gate.failures,
+    enforced: blockingFailures(gate.failures),
   }, null, 2)}\n`);
-  return gate.verdict === 'PASS' ? 0 : 1;
+  // ADR-0091 D7.6: the exit code derives from the INTEGRITY failures only. A floor miss stays in the
+  // report (state/failures) and is never fatal -- exiting 1 on it would silently restore the blocking
+  // ratchet ADR-086's 2026-09-15 amendment removed, the moment anyone re-accepts the floor.
+  return blockingFailures(gate.failures).length ? 1 : 0;
 }
 
 // Realpath both sides: argv[1] is whatever the caller typed, while Node resolves import.meta.url

package/scripts/public-verification-inputs.mjs

@@ -250,6 +250,19 @@ function retrospectiveBaselineFromTree({ extractedRoot, bundleFile, expectedTag,
   return { receipt, bytes, fileSha256: crypto.createHash('sha256').update(bytes).digest('hex'), root, archiveManifest };
 }
 
+/**
+ * ADR-0091 D6.3: does the baseline archive carry the seed's own published tag? A code-release seed
+ * (vX.Y.Z) records that tag in its generation ledger. A corpus-generation seed CANNOT: its tag is
+ * corpus-sha256-<the archive's own digest>, which no file inside the archive can contain, and its
+ * ledger names the runtime that built it. So a content-addressed tag is proven by the archive digest
+ * it names; every other tag must equal the ledger's releaseTag, exactly as before.
+ */
+export function baselineTagMatches({ publishedTag, ledgerReleaseTag, archiveSha256 }) {
+  const contentAddressed = /^corpus-sha256-([0-9a-f]{64})$/.exec(String(publishedTag || ''));
+  if (contentAddressed) return contentAddressed[1] === archiveSha256;
+  return typeof publishedTag === 'string' && publishedTag.length > 0 && ledgerReleaseTag === publishedTag;
+}
+
 function observedBaselineFromTree({ extractedRoot, bundleFile, expectedTag, expectedSha256, expectedBytes }) {
   const ledgerFile = findNamed(extractedRoot, 'RVF-GENERATIONS.json');
   const root = path.dirname(ledgerFile);
@@ -259,7 +272,9 @@ function observedBaselineFromTree({ extractedRoot, bundleFile, expectedTag, expe
     fail('historical baseline generation ledger is malformed');
   }
   const archive = namedIdentity(bundleFile);
-  if (ledger.releaseTag !== expectedTag) fail('historical baseline differs from the expected public release tag');
+  if (!baselineTagMatches({ publishedTag: expectedTag, ledgerReleaseTag: ledger.releaseTag, archiveSha256: archive.sha256 })) {
+    fail('historical baseline differs from the expected public release tag');
+  }
   if (!HEX64.test(String(expectedSha256 || '')) || archive.sha256 !== expectedSha256) {
     fail('historical baseline differs from the expected public archive SHA-256');
   }
@@ -476,7 +491,8 @@ export async function createPublicVerificationInputs({ baselineBundle, candidate
         fail('baseline archive bytes differ from release coverage');
       }
       if (seed.receiptSha256 !== baselineProof.fileSha256) fail('baseline receipt differs from release coverage');
-      if (seed.tag !== baselineProof.receipt.releaseTag) {
+      if (!baselineTagMatches({ publishedTag: seed.tag, ledgerReleaseTag: baselineProof.receipt.releaseTag,
+        archiveSha256: baselineProof.receipt.archive.sha256 })) {
         fail('baseline release tag differs from release coverage');
       }
       const baselineStores = baselineProof.receipt.stores.map(({ name }) => name);