ruvnet-brain 4.3.34 → 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/oracle/retrieval-accuracy.mjs

@@ -34,6 +34,14 @@
 // complete. A bounded run can therefore be read, reported and compared, but it can never seal a
 // publishable corpus receipt.
 //
+// QUESTION SAMPLING (ADR-0091 D2). `--sample-questions <n>` measures n oracle questions in total,
+// chosen by selectQuestionSample(): stratified across partitions (one question from each of n
+// partitions before any partition gets a second) and ordered by sha256(seed, id), so the same
+// seed, oracle and n always select the same questions. It exists because the full diagnostic is
+// ~1,164 queries at ~4.2 s each on a hosted runner (82 minutes), and C3 no longer blocks anything.
+// A sampled report is bounded like any other bounded run: `coverage.complete: false`, the seed and
+// the exact selected label ids recorded in `coverage.bounded.sample`. Omit the flag for the full audit.
+//
 // TIMEOUTS. The threshold text says errors and timeouts count as failures (they are never excluded
 // from the denominator), and the Step 15 proof text additionally names "timeout" as a standalone
 // blocker. Both readings are honoured, strictly: a timeout is counted as a failure in the
@@ -74,6 +82,12 @@ export const THRESHOLD_DENOMINATOR = 20;
 export const QUERY_MODES = Object.freeze(['explicit-repository', 'full-corpus']);
 export const DEFAULT_QUERY_TIMEOUT_MS = 120_000;
 export const DEFAULT_ORACLE_FILE = 'data/retrieval-accuracy-oracle.json';
+// ADR-0091 D2 — the sample the corpus pipeline measures. 80 questions x 2 modes = 160 queries. At the
+// hosted-runner cost of 4.23 s/query (82 min / 1,164 queries, the ADR's measured C3 run) that is
+// 677 s of querying, ~11.3 min, leaving ~3.7 min of the 15-minute bound for extraction and model
+// load. corpus-seed.yml passes this same number; a unit test pins the two together.
+export const C3_DIAGNOSTIC_SAMPLE_QUESTIONS = 80;
+export const DEFAULT_SAMPLE_SEED = 'c3-diagnostic-sample/1';
 
 const HEX64 = /^[a-f0-9]{64}$/;
 const HEX40 = /^[a-f0-9]{40}$/;
@@ -357,6 +371,37 @@ export function archiveStores(root) {
     .sort();
 }
 
+/**
+ * Deterministic, stratified question sample (ADR-0091 D2). Partitions are ranked by
+ * sha256(seed, partition) and each partition's labels by sha256(seed, label id); the sample takes one
+ * label from every partition in rank order, then a second from every partition that has one, and so
+ * on until `size` labels are chosen. Same seed + same oracle + same size = same labels, always.
+ * Returns the chosen labels sorted by id.
+ */
+export function selectQuestionSample({ labels, size, seed = DEFAULT_SAMPLE_SEED }) {
+  if (!Number.isSafeInteger(size) || size <= 0) fail('question sample size must be a positive integer');
+  if (typeof seed !== 'string' || !seed) fail('question sample seed must be a non-empty string');
+  const rank = (value) => sha256Of(`${seed}\u0000${value}`);
+  const byPartition = new Map();
+  for (const label of labels) {
+    if (!byPartition.has(label.partition)) byPartition.set(label.partition, []);
+    byPartition.get(label.partition).push({ label, key: rank(`label\u0000${label.id}`) });
+  }
+  const queues = [...byPartition.entries()]
+    .map(([partition, rows]) => ({ key: rank(`partition\u0000${partition}`), rows: rows.sort((a, b) => a.key.localeCompare(b.key)) }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+  const chosen = [];
+  for (let depth = 0; chosen.length < size; depth += 1) {
+    let took = false;
+    for (const queue of queues) {
+      if (chosen.length >= size) break;
+      if (depth < queue.rows.length) { chosen.push(queue.rows[depth].label); took = true; }
+    }
+    if (!took) break; // the oracle has fewer labels than requested: the sample is every label
+  }
+  return chosen.sort((a, b) => a.id.localeCompare(b.id));
+}
+
 async function defaultSearch({ dir, query, repos, timeoutMs }) {
   const module = await import('../../kb/forge-ask-all.mjs');
   let timer = null;
@@ -393,6 +438,8 @@ export async function runRetrievalAccuracy({
   outFile,
   storeLimit = null,
   sampleLimit = null,
+  sampleQuestions = null,
+  sampleSeed = DEFAULT_SAMPLE_SEED,
   modes = QUERY_MODES,
   timeoutMs = DEFAULT_QUERY_TIMEOUT_MS,
   search = defaultSearch,
@@ -407,6 +454,14 @@ export async function runRetrievalAccuracy({
   const oracle = readAccuracyOracle(oracleFile);
   const selectedModes = QUERY_MODES.filter((mode) => modes.includes(mode));
   if (!selectedModes.length) fail('no supported query mode selected');
+  if (sampleQuestions != null && (storeLimit != null || sampleLimit != null)) {
+    fail('--sample-questions is a whole-oracle sample; it cannot be combined with --stores or --sample');
+  }
+  const questionSample = sampleQuestions == null ? null
+    : selectQuestionSample({ labels: oracle.labels, size: sampleQuestions, seed: sampleSeed });
+  const sampledIds = questionSample ? new Set(questionSample.map((label) => label.id)) : null;
+  // Any sampling at all measures only what it sampled: unproduced slots are not charged and n is not N.
+  const sampling = sampleLimit != null || questionSample != null;
 
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'retrieval-accuracy-'));
   try {
@@ -437,7 +492,9 @@ export async function runRetrievalAccuracy({
       labelsByPartition.get(label.partition).push(label);
     }
     const orderedPartitions = [...oracle.partitions.values()].sort((a, b) => a.partition.localeCompare(b.partition));
-    const measuredPartitions = storeLimit == null ? orderedPartitions : orderedPartitions.slice(0, storeLimit);
+    const measuredPartitions = sampledIds
+      ? orderedPartitions.filter((row) => (labelsByPartition.get(row.partition) || []).some((label) => sampledIds.has(label.id)))
+      : storeLimit == null ? orderedPartitions : orderedPartitions.slice(0, storeLimit);
 
     const partitions = [];
     let timeouts = 0;
@@ -446,12 +503,13 @@ export async function runRetrievalAccuracy({
       const all = (labelsByPartition.get(partition.partition) || [])
         .slice()
         .sort((a, b) => a.id.localeCompare(b.id));
-      const selected = sampleLimit == null ? all : all.slice(0, sampleLimit);
+      const selected = sampledIds ? all.filter((label) => sampledIds.has(label.id))
+        : sampleLimit == null ? all : all.slice(0, sampleLimit);
       // THE DENOMINATOR. For a compliant oracle N comes from the unit inventory — 2 x min(100, U) —
       // never from how many labels happened to survive production. Every unproduced unit keeps its two
       // slots and scores them as misses below. A bounded --sample run is incomplete and unacceptable
       // regardless, so it measures only what it sampled.
-      const unproducedSlots = oracle.c3Eligible && sampleLimit == null ? partition.unproduced : [];
+      const unproducedSlots = oracle.c3Eligible && !sampling ? partition.unproduced : [];
       for (const mode of selectedModes) {
         const row = {
           partition: partition.partition,
@@ -466,7 +524,7 @@ export async function runRetrievalAccuracy({
           failures: 0,
           errors: 0,
           timeouts: 0,
-          sampled: sampleLimit != null && selected.length < all.length,
+          sampled: sampling && selected.length < all.length,
           oracleRows: all.length,
           failedLabels: [],
         };
@@ -514,7 +572,7 @@ export async function runRetrievalAccuracy({
         if (row.successes + row.failures !== row.n) {
           fail(`internal: partition ${row.partition} (${mode}) scored ${row.successes + row.failures} outcomes for n=${row.n}`);
         }
-        if (oracle.c3Eligible && sampleLimit == null && row.n !== row.N) {
+        if (oracle.c3Eligible && !sampling && row.n !== row.N) {
           fail(`internal: partition ${row.partition} (${mode}) measured n=${row.n} but its inventory fixes N=${row.N}`);
         }
         row.state = meetsThreshold(row.successes, row.n) && row.timeouts === 0 ? 'PASS' : 'FAIL';
@@ -533,6 +591,7 @@ export async function runRetrievalAccuracy({
     const boundedReasons = [];
     if (storeLimit != null) boundedReasons.push(`--stores ${storeLimit}`);
     if (sampleLimit != null) boundedReasons.push(`--sample ${sampleLimit}`);
+    if (questionSample) boundedReasons.push(`--sample-questions ${sampleQuestions} (seed ${sampleSeed}): ${questionSample.length} of ${oracle.labels.length} oracle questions`);
     if (selectedModes.length !== QUERY_MODES.length) boundedReasons.push(`--modes ${selectedModes.join(',')}`);
     if (unmeasuredPartitions.length) boundedReasons.push(`${unmeasuredPartitions.length} oracle partition(s) not measured`);
     if (uncoveredArchiveStores.length) boundedReasons.push(`${uncoveredArchiveStores.length} shipped store(s) with no oracle coverage`);
@@ -568,7 +627,14 @@ export async function runRetrievalAccuracy({
       queryTimeoutMs: timeoutMs,
       coverage: {
         complete,
-        bounded: complete ? null : { reasons: boundedReasons, storeLimit, sampleLimit, modes: selectedModes },
+        bounded: complete ? null : {
+          reasons: boundedReasons, storeLimit, sampleLimit, modes: selectedModes,
+          ...(questionSample ? { sample: {
+            method: 'stratified-by-partition/sha256-rank', seed: sampleSeed, requested: sampleQuestions,
+            questions: questionSample.length, oracleQuestions: oracle.labels.length,
+            labelIds: questionSample.map((label) => label.id),
+          } } : {}),
+        },
         archiveStores: shipped,
         oraclePartitions: orderedPartitions.length,
         measuredPartitions: measuredPartitions.length,
@@ -778,6 +844,8 @@ export async function main(argv = process.argv.slice(2)) {
     outFile: arg(argv, '--out'),
     storeLimit: positiveInt(arg(argv, '--stores'), '--stores'),
     sampleLimit: positiveInt(arg(argv, '--sample'), '--sample'),
+    sampleQuestions: positiveInt(arg(argv, '--sample-questions'), '--sample-questions'),
+    sampleSeed: arg(argv, '--sample-seed', DEFAULT_SAMPLE_SEED),
     modes: arg(argv, '--modes') ? String(arg(argv, '--modes')).split(',').map((mode) => mode.trim()) : QUERY_MODES,
     timeoutMs: positiveInt(arg(argv, '--timeout-ms'), '--timeout-ms') || DEFAULT_QUERY_TIMEOUT_MS,
   });

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