ruvnet-brain 4.3.33 → 4.3.35

package/scripts/corpus-next-seed.mjs

@@ -11,27 +11,48 @@
 // unsigned or half-uploaded release — it falls back to the committed data/corpus-seed.json, which is
 // the bootstrap/recovery input and is content-addressed independently.
 //
-// "Compatible" is decided against the SAME approved runtime pin that gates promotion
-// (scripts/approved-runtime.mjs): a generation whose archive shipped a different brainVersion is a
-// different runtime, and seeding from it would drag unapproved executables forward through reuse.
+// "Compatible" means THIS RUNTIME CAN CONSUME THE SEED (ADR-0091 D4). It is NOT "the generation
+// shipped the same runtime version as the approved pin": that rule rejected every generation the
+// moment a code release moved the approved runtime, so the seed chain reset to the weeks-stale
+// bootstrap on every release (ADR-0091 section 3.4). The runtime's executables never come from a
+// seed anyway -- build-bundle.mjs copies runtime modules from the checkout and only named store
+// files from the seed, and verifyApprovedRuntime's backward check still refuses any unpinned
+// executable in the candidate. So --pin is gone from this script entirely. What CAN make a seed
+// unusable is judged here, from small files, BEFORE the ~500 MB archive is ever fetched:
+//   1. the receipt (schema 3, as before) records every store's embedding model and dimensions, and
+//      they must equal what this runtime's forge build produces (kb/forge-corpus.mjs
+//      FORGE_BUILD_FINGERPRINT) -- vectors from another model are not searchable by this one;
+//   2. the generation's detached .recall.json must be the one its receipt binds, must have been
+//      measured against THIS runtime's frozen fixture digest, and must pass THIS runtime's
+//      readRecallReport -- the same reader and arguments corpus-seed.yml's downstream seed
+//      re-check uses, so that re-check (which has no fallback) only ever sees a generation that
+//      already passed here.
+// "This runtime" is --runtime-root: the source tree whose readers will consume the seed. On the
+// nightly that is the approved runtime's own sourceSha (ADR-0091 D3), which usually trails main.
+// It defaults to this checkout, which is right whenever the checkout IS the build source.
+//
+// A generation that fails any check is SKIPPED with its reason, never a failure: the walk moves to
+// the next older one. At most SEARCH_BOUND (5) generations are judged, so one bad format change can
+// never turn into an unbounded walk of release history; after that the committed bootstrap is used.
 //
 // "Verified" is decided by evidence that is checkable without downloading 500 MB here: the tag must
 // be the content-addressed corpus-sha256-<digest> form, the release must not be a draft, and it must
-// carry all three of ruvnet-brain.zip, its detached .sig, and corpus-receipt.json, with the receipt's
-// own archive digest equal to the digest in the tag. The full byte-level proof still happens
-// downstream where the archive is actually fetched (corpus-seed.yml re-checks sha256 and byte length
-// before reconciliation, and corpus-candidate.mjs re-derives the whole candidate from the bytes).
+// carry exactly one of each of ruvnet-brain.zip, its detached .sig, corpus-receipt.json and both
+// detached reports, with the receipt's own archive digest equal to the digest in the tag. The full
+// byte-level proof still happens downstream where the archive is actually fetched (corpus-seed.yml
+// re-checks sha256 and byte length before reconciliation, corpus-reconcile.mjs checks the ledger
+// schema after extraction, and corpus-candidate.mjs re-derives the whole candidate from the bytes).
 //
 // Usage:
-//   node scripts/corpus-next-seed.mjs --repo owner/name [--pin data/approved-runtime.json]
+//   node scripts/corpus-next-seed.mjs --repo owner/name [--runtime-root <source tree>]
 //                                     [--bootstrap data/corpus-seed.json] [--out <file>]
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { readApprovedRuntime, validateApprovedRuntime } from './approved-runtime.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HEX64 = /^[0-9a-f]{64}$/;
@@ -39,6 +60,13 @@ const CORPUS_TAG = /^corpus-sha256-([0-9a-f]{64})$/;
 const ARCHIVE_ASSET = 'ruvnet-brain.zip';
 const SIGNATURE_ASSET = 'ruvnet-brain.zip.sig';
 const RECEIPT_ASSET = 'corpus-receipt.json';
+const RECALL_ASSET = 'ruvnet-brain.zip.recall.json';
+const ACCURACY_ASSET = 'ruvnet-brain.zip.accuracy.json';
+// Every asset corpus-seed.yml requires of a digest-derived seed, plus the two judged here. A release
+// missing one would pass this resolver and then fail the downstream step that has no fallback.
+const REQUIRED_ASSETS = [ARCHIVE_ASSET, SIGNATURE_ASSET, RECEIPT_ASSET, RECALL_ASSET, ACCURACY_ASSET];
+/** ADR-0091 D4: judge at most this many of the newest generations, then use the committed bootstrap. */
+export const SEARCH_BOUND = 5;
 
 const defaultRun = (command, args, options) => spawnSync(command, args, { encoding: 'utf8', ...options });
 
@@ -61,69 +89,132 @@ export function validateBootstrapSeed(seed) {
   return failures;
 }
 
+/** "forge-corpus-v1|Xenova/bge-base-en-v1.5@<rev>:768:cls" -> { model, dimensions }. */
+export function parseBuildFingerprint(fingerprint) {
+  const match = /\|([^@|]+)@[^:|]+:(\d+):[^|]*$/.exec(String(fingerprint || ''));
+  if (!match) throw new Error(`cannot read the embedding model from FORGE_BUILD_FINGERPRINT (${fingerprint})`);
+  return { model: match[1], dimensions: Number(match[2]) };
+}
+
+/**
+ * What the consuming runtime expects of a seed, read from THAT runtime's own source tree -- never
+ * restated here. A tree that cannot answer is a code defect, so this throws (a loud red night)
+ * rather than quietly seeding from the bootstrap every night, which would look exactly like "no new
+ * generation yet".
+ */
+export async function loadCompatibilityProfile({ runtimeRoot = ROOT, fixtureFile = null } = {}) {
+  const root = path.resolve(runtimeRoot);
+  const load = (relative) => import(pathToFileURL(path.join(root, relative)).href);
+  const [recall, forge] = await Promise.all([load('scripts/oracle/repo-recall.mjs'), load('kb/forge-corpus.mjs')]);
+  if (typeof recall.readRecallReport !== 'function' || typeof recall.loadFixture !== 'function') {
+    throw new Error(`${root} has no repo-recall reader to judge a seed with`);
+  }
+  const { model, dimensions } = parseBuildFingerprint(forge.FORGE_BUILD_FINGERPRINT);
+  return {
+    runtimeRoot: root,
+    model,
+    dimensions,
+    fixtureSha256: recall.loadFixture(fixtureFile || path.join(root, recall.DEFAULT_FIXTURE_FILE)).fixtureSha256,
+    floorValue: recall.ABSOLUTE_FLOOR,
+    readRecallReport: recall.readRecallReport,
+  };
+}
+
+function download(run, { repo, tag, pattern, dir }) {
+  const result = run('gh', ['release', 'download', tag, '--repo', repo, '--pattern', pattern, '--dir', dir],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  const file = path.join(dir, pattern);
+  return !result.error && result.status === 0 && fs.existsSync(file) ? file : null;
+}
+
+// Small files only (a receipt, a recall report): read whole.
+const sha256Of = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
 /**
  * One published release, judged. Returns null when it cannot serve as a seed, with the reason
- * recorded on `rejected` so a no-op night is explainable rather than silent.
+ * recorded on `rejected` so a no-op night is explainable rather than silent. Never downloads the
+ * archive: every check below reads the release's asset list, its receipt, or its recall report.
  */
-function judgeRelease({ run, repo, tag, digest, approved, rejected }) {
+function judgeRelease({ run, repo, tag, digest, profile, rejected }) {
+  const reject = (reason) => { rejected.push({ tag, reason }); return null; };
   let view;
   try {
     view = ghJson(run, ['release', 'view', tag, '--repo', repo, '--json', 'tagName,isDraft,assets']);
   } catch (error) {
-    rejected.push({ tag, reason: `release view failed (${error.message})` });
-    return null;
-  }
-  if (view?.tagName !== tag || view.isDraft) {
-    rejected.push({ tag, reason: 'release is a draft or names another tag' });
-    return null;
+    return reject(`release view failed (${error.message})`);
   }
+  if (view?.tagName !== tag || view.isDraft) return reject('release is a draft or names another tag');
   const assets = Array.isArray(view.assets) ? view.assets : [];
   const named = (name) => assets.filter((asset) => asset?.name === name);
-  for (const name of [ARCHIVE_ASSET, SIGNATURE_ASSET, RECEIPT_ASSET]) {
-    if (named(name).length !== 1) {
-      rejected.push({ tag, reason: `unverified: expected exactly one ${name} asset` });
-      return null;
-    }
+  for (const name of REQUIRED_ASSETS) {
+    if (named(name).length !== 1) return reject(`unverified: expected exactly one ${name} asset`);
   }
   const archive = named(ARCHIVE_ASSET)[0];
-  if (!Number.isSafeInteger(archive.size) || archive.size < 1) {
-    rejected.push({ tag, reason: 'unverified: archive asset has no usable byte length' });
-    return null;
-  }
+  if (!Number.isSafeInteger(archive.size) || archive.size < 1) return reject('unverified: archive asset has no usable byte length');
 
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-next-seed-'));
   try {
-    const download = run('gh', ['release', 'download', tag, '--repo', repo, '--pattern', RECEIPT_ASSET, '--dir', scratch],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-    if (download.error || download.status !== 0) {
-      rejected.push({ tag, reason: 'unverified: corpus receipt could not be downloaded' });
-      return null;
-    }
+    const receiptFile = download(run, { repo, tag, pattern: RECEIPT_ASSET, dir: scratch });
+    if (!receiptFile) return reject('unverified: corpus receipt could not be downloaded');
     let receipt;
-    try { receipt = JSON.parse(fs.readFileSync(path.join(scratch, RECEIPT_ASSET), 'utf8')); }
-    catch (error) { rejected.push({ tag, reason: `unverified: corpus receipt unreadable (${error.message})` }); return null; }
+    try { receipt = JSON.parse(fs.readFileSync(receiptFile, 'utf8')); }
+    catch (error) { return reject(`unverified: corpus receipt unreadable (${error.message})`); }
 
     // ADR-086 Step 15 / A6 moved the corpus receipt to schemaVersion 3 (it now binds the detached
     // retrieval-accuracy report). This reader has to move with it: left at 2 it would reject every
     // schema-3 generation as unverified and silently fall back to the committed bootstrap seed every
     // night — a degradation that looks exactly like "no new generation yet".
     if (receipt.schemaVersion !== 3 || receipt.kind !== 'ruvnet-brain-corpus-candidate') {
-      rejected.push({ tag, reason: 'unverified: receipt schema or kind is not a schema-3 corpus candidate' });
-      return null;
+      return reject('unverified: receipt schema or kind is not a schema-3 corpus candidate');
     }
-    if (!receipt.accuracyReport?.file || !/^[a-f0-9]{64}$/.test(String(receipt.accuracyReport.sha256 || ''))
+    if (!receipt.accuracyReport?.file || !HEX64.test(String(receipt.accuracyReport.sha256 || ''))
       || !Number.isSafeInteger(receipt.accuracyReport.bytes)) {
-      rejected.push({ tag, reason: 'unverified: receipt carries no retrieval-accuracy binding' });
-      return null;
+      return reject('unverified: receipt carries no retrieval-accuracy binding');
     }
     if (receipt.archive?.sha256 !== digest || receipt.archive?.bytes !== archive.size) {
-      rejected.push({ tag, reason: 'unverified: receipt archive identity disagrees with the content-addressed tag' });
-      return null;
+      return reject('unverified: receipt archive identity disagrees with the content-addressed tag');
+    }
+    if (receipt.recallReport?.file !== RECALL_ASSET || !HEX64.test(String(receipt.recallReport?.sha256 || ''))
+      || !Number.isSafeInteger(receipt.recallReport?.bytes)) {
+      return reject('unverified: receipt carries no repo-recall binding');
+    }
+
+    // D4 check 1 -- embedding model and dimensions, per store, from the receipt alone.
+    const stores = Array.isArray(receipt.stores) ? receipt.stores : [];
+    if (!stores.length) return reject('unverified: receipt lists no stores');
+    const foreign = stores.filter((row) => row?.model !== profile.model || row?.dimensions !== profile.dimensions);
+    if (foreign.length) {
+      const first = foreign[0];
+      return reject(`incompatible: ${foreign.length} store(s) embedded with a different model/dimensions `
+        + `(e.g. ${first?.name}: ${first?.model}/${first?.dimensions}); this runtime builds ${profile.model}/${profile.dimensions}`);
     }
-    if (receipt.archiveManifestVersion !== approved.brainVersion || receipt.archiveManifestReleaseTag !== approved.releaseTag) {
-      rejected.push({ tag, reason: `incompatible: generation shipped runtime ${receipt.archiveManifestReleaseTag}, approved runtime is ${approved.releaseTag}` });
-      return null;
+
+    // D4 check 2 -- the recall report, the one small file that decides whether the downstream seed
+    // re-check can pass. Downloaded only now, after the receipt already qualified.
+    const recallFile = download(run, { repo, tag, pattern: RECALL_ASSET, dir: scratch });
+    if (!recallFile) return reject('unverified: repo-recall report could not be downloaded');
+    if (sha256Of(recallFile) !== receipt.recallReport.sha256 || fs.statSync(recallFile).size !== receipt.recallReport.bytes) {
+      return reject('unverified: repo-recall report is not the one the receipt binds');
+    }
+    let claimedFixture = null;
+    try { claimedFixture = JSON.parse(fs.readFileSync(recallFile, 'utf8'))?.fixture?.sha256 ?? null; } catch { /* the reader names it below */ }
+    if (claimedFixture !== profile.fixtureSha256) {
+      return reject(`incompatible: recall report was measured against fixture ${String(claimedFixture).slice(0, 12)}, `
+        + `this runtime's frozen fixture is ${profile.fixtureSha256.slice(0, 12)}`);
     }
+    try {
+      profile.readRecallReport({
+        reportFile: recallFile,
+        archive: { file: ARCHIVE_ASSET, sha256: digest, bytes: archive.size },
+        expectedFixtureSha256: profile.fixtureSha256,
+        // The same bar corpus-seed.yml's seed re-check uses: a published seed is graded against the
+        // fixed ABSOLUTE_FLOOR, never re-judged by a later, higher committed floor.
+        floorValue: profile.floorValue,
+      });
+    } catch (error) {
+      return reject(`incompatible: recall report fails this runtime's reader (${error.message})`);
+    }
+
     return {
       origin: 'published-generation',
       tag,
@@ -131,27 +222,29 @@ function judgeRelease({ run, repo, tag, digest, approved, rejected }) {
       sha256: digest,
       bytes: archive.size,
       sourceCommit: typeof receipt.builderSourceSha === 'string' ? receipt.builderSourceSha : null,
-      brainVersion: receipt.archiveManifestVersion,
+      // Informational only since D4: the runtime that BUILT the seed, which may be older than the
+      // runtime about to consume it. Nothing gates on it.
+      brainVersion: receipt.archiveManifestVersion ?? null,
     };
   } finally {
     fs.rmSync(scratch, { recursive: true, force: true });
   }
 }
 
-export function resolveNextCorpusSeed({
-  repo, run = defaultRun, root = ROOT, pinFile, bootstrapFile, limit = 100,
+export async function resolveNextCorpusSeed({
+  repo, run = defaultRun, root = ROOT, runtimeRoot = null, fixtureFile = null, bootstrapFile,
+  limit = 100, searchBound = SEARCH_BOUND, profile = null,
 } = {}) {
   if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('--repo must be owner/name');
-
-  const approved = readApprovedRuntime(pinFile || path.join(root, 'data/approved-runtime.json'));
-  const pinFailures = validateApprovedRuntime(approved);
-  if (pinFailures.length) throw new Error(`approved runtime pin is invalid: ${pinFailures.join('; ')}`);
+  if (!Number.isSafeInteger(searchBound) || searchBound < 1) throw new Error('search bound must be a positive integer');
 
   const bootstrapPath = path.resolve(bootstrapFile || path.join(root, 'data/corpus-seed.json'));
   const bootstrap = JSON.parse(fs.readFileSync(bootstrapPath, 'utf8'));
   const bootstrapFailures = validateBootstrapSeed(bootstrap);
   if (bootstrapFailures.length) throw new Error(`committed bootstrap seed is invalid: ${bootstrapFailures.join('; ')}`);
 
+  const compatibility = profile || await loadCompatibilityProfile({ runtimeRoot: runtimeRoot || root, fixtureFile });
+
   const rejected = [];
   let listed = [];
   try {
@@ -174,9 +267,14 @@ export function resolveNextCorpusSeed({
   }
   candidates.sort((left, right) => right.createdAt - left.createdAt);
 
-  for (const candidate of candidates) {
-    const resolved = judgeRelease({ run, repo, tag: candidate.tag, digest: candidate.digest, approved, rejected });
-    if (resolved) return { seed: resolved, rejected, approvedRuntime: approved.releaseTag };
+  const judged = candidates.slice(0, searchBound);
+  for (const skipped of candidates.slice(searchBound)) {
+    rejected.push({ tag: skipped.tag, reason: `not judged: older than the ${searchBound} newest generations (ADR-0091 D4 search bound)` });
+  }
+  const expects = { model: compatibility.model, dimensions: compatibility.dimensions, fixtureSha256: compatibility.fixtureSha256 };
+  for (const candidate of judged) {
+    const resolved = judgeRelease({ run, repo, tag: candidate.tag, digest: candidate.digest, profile: compatibility, rejected });
+    if (resolved) return { seed: resolved, rejected, judged: judged.length, expects };
   }
 
   return {
@@ -190,36 +288,59 @@ export function resolveNextCorpusSeed({
       brainVersion: null,
     },
     rejected,
-    approvedRuntime: approved.releaseTag,
+    judged: judged.length,
+    expects,
   };
 }
 
-const arg = (name, fallback) => {
-  const index = process.argv.indexOf(name);
-  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+const arg = (argv, name, fallback) => {
+  const index = argv.indexOf(name);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
 };
 
-function main() {
+export async function main(argv = process.argv.slice(2), { run = defaultRun, stdout = process.stdout, stderr = process.stderr } = {}) {
+  // Loud, not ignored: a caller still passing --pin is on the pre-D4 contract and should be told.
+  if (argv.includes('--pin')) {
+    stderr.write('[corpus-next-seed] --pin was removed by ADR-0091 D4: seed selection no longer depends on the approved runtime pin\n');
+    return 2;
+  }
   let result;
   try {
-    result = resolveNextCorpusSeed({
-      repo: arg('--repo', process.env.GITHUB_REPOSITORY),
-      pinFile: arg('--pin'),
-      bootstrapFile: arg('--bootstrap'),
+    result = await resolveNextCorpusSeed({
+      repo: arg(argv, '--repo', process.env.GITHUB_REPOSITORY),
+      runtimeRoot: arg(argv, '--runtime-root', null),
+      fixtureFile: arg(argv, '--fixture', null),
+      bootstrapFile: arg(argv, '--bootstrap', null),
+      run,
     });
   } catch (error) {
-    console.error(`[corpus-next-seed] ${error.message}`);
+    stderr.write(`[corpus-next-seed] ${error.message}\n`);
     return 1;
   }
-  for (const row of result.rejected) console.error(`[corpus-next-seed] skipped ${row.tag || '(list)'}: ${row.reason}`);
-  const out = arg('--out');
+  for (const row of result.rejected) stderr.write(`[corpus-next-seed] skipped ${row.tag || '(list)'}: ${row.reason}\n`);
+  const out = arg(argv, '--out', null);
   const serialized = `${JSON.stringify(result.seed, null, 2)}\n`;
   if (out) fs.writeFileSync(path.resolve(out), serialized);
-  process.stdout.write(serialized);
-  console.error(`[corpus-next-seed] ${result.seed.origin} ${result.seed.tag} (approved runtime ${result.approvedRuntime})`);
+  stdout.write(serialized);
+  stderr.write(`[corpus-next-seed] ${result.seed.origin} ${result.seed.tag} (judged ${result.judged} generation(s) against `
+    + `${result.expects.model}/${result.expects.dimensions}, fixture ${result.expects.fixtureSha256.slice(0, 12)})\n`);
   return 0;
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
-  process.exitCode = main();
+// REALPATH BOTH SIDES (ADR-0091 D12.2, applied here because this file is rewritten anyway): a plain
+// argv[1]-vs-import.meta.url comparison is false under a symlinked path such as macOS's /var/folders
+// temp directories, and the CLI then exits 0 having done nothing.
+function isMain() {
+  try {
+    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(`[corpus-next-seed] ${error?.message || error}`);
+    process.exitCode = 1;
+  });
 }

package/scripts/corpus-reconcile.mjs

@@ -20,7 +20,7 @@ import { fileIdentity } from '../plugin/scripts/coverage-integrity.mjs';
 import { readDiagnosticAccuracyReport } from './oracle/retrieval-accuracy.mjs';
 import { storeRoot } from '../kb/store-root.mjs';
 import { captureGistSources } from './gist-receipts.mjs';
-import { projectSourceStore } from './rvf-generation.mjs';
+import { projectSourceStore, RUNTIME_LEDGER_KIND } from './rvf-generation.mjs';
 
 export { rebuildCorpusAggregates };
 
@@ -119,6 +119,40 @@ function filesNamed(root, wanted) {
   return found;
 }
 
+// ADR-0091 D4 -- the ONE seed property that cannot be judged before download. corpus-next-seed.mjs
+// judges a published generation's embedding model and recall report from small files, but the
+// generation ledger lives only inside the archive, so its schema is checked here, right after
+// extraction and BEFORE anything is moved. A mismatch is not a corrupt seed: it is a seed this runtime
+// cannot consume (a ledger-schema change is a code-release event). It is thrown as a distinct error
+// and main() exits SEED_LEDGER_INCOMPATIBLE_EXIT with the assets directory untouched, so
+// corpus-seed.yml can re-run seed extraction ONCE from the committed bootstrap in the same job.
+export const SEED_LEDGER_SCHEMA_VERSION = 2;
+export const SEED_LEDGER_INCOMPATIBLE_EXIT = 3;
+
+export class SeedLedgerIncompatibleError extends Error {
+  constructor(reason) {
+    super(`[corpus-reconcile] seed ledger is incompatible with this runtime: ${reason}`);
+    this.name = 'SeedLedgerIncompatibleError';
+    this.reason = reason;
+  }
+}
+
+/** null when this runtime can consume the ledger, else the reason it cannot. */
+export function seedLedgerIncompatibility(ledger) {
+  if (!ledger || typeof ledger !== 'object' || Array.isArray(ledger)) return 'RVF-GENERATIONS.json is not an object';
+  if (ledger.schemaVersion !== SEED_LEDGER_SCHEMA_VERSION || ledger.kind !== RUNTIME_LEDGER_KIND) {
+    return `RVF-GENERATIONS.json is schemaVersion ${JSON.stringify(ledger.schemaVersion ?? null)} kind ${JSON.stringify(ledger.kind ?? null)}; `
+      + `this runtime reads schemaVersion ${SEED_LEDGER_SCHEMA_VERSION} kind ${RUNTIME_LEDGER_KIND}`;
+  }
+  if (!ledger.stores || typeof ledger.stores !== 'object' || Array.isArray(ledger.stores)) return 'RVF-GENERATIONS.json has no stores object';
+  return null;
+}
+
+// Moves the corpus root's TOP-LEVEL entries only (directories such as keys/, primer/ and l2/ move
+// whole). Nothing is filtered out: a seed's own runtime files (.mjs, package.json) are harmless here,
+// because build-bundle.mjs copies only named store files and the sealed prose from --assets and takes
+// every runtime module from the checkout (ADR-0091 D4 withdrew the 0.1.0 "strip" step for that reason,
+// and because source-coverage.mjs hard-reads capability-cards.md from these assets).
 export function normalizeExtractedCorpus({ extractedDir, assetsDir }) {
   const extracted = path.resolve(extractedDir || '');
   const assets = path.resolve(assetsDir || '');
@@ -128,6 +162,11 @@ export function normalizeExtractedCorpus({ extractedDir, assetsDir }) {
   if (fs.existsSync(assets) && fs.readdirSync(assets).length) fail(`bootstrap assets directory is not empty (${assets})`);
   const ledgers = filesNamed(extracted, 'RVF-GENERATIONS.json');
   if (ledgers.length !== 1) fail(`seed archive must contain exactly one RVF-GENERATIONS.json; found ${ledgers.length}`);
+  let seedLedger;
+  try { seedLedger = JSON.parse(fs.readFileSync(ledgers[0], 'utf8')); }
+  catch (error) { throw new SeedLedgerIncompatibleError(`RVF-GENERATIONS.json is unreadable (${error.message})`); }
+  const incompatibility = seedLedgerIncompatibility(seedLedger);
+  if (incompatibility) throw new SeedLedgerIncompatibleError(incompatibility);
   const corpusRoot = path.dirname(ledgers[0]);
   // A published seed's own PRIVATE-STORES.json is AUTHENTICATED HISTORICAL EVIDENCE of what that
   // prior round excluded — never the current builder's live policy. Keep it under a distinct name
@@ -306,6 +345,33 @@ export async function acquireSealedGeneration({ maxAttempts = 3, assetsDir = nul
     + 'eligible source(s) remain unresolved against the sealed manifest');
 }
 
+/**
+ * The ONE reader of an acquisition result's per-attempt history (ADR-0091 D1).
+ *
+ * WHY THIS EXISTS. cd0f032f renamed the loop's history from `rounds` to `attempts` but left two
+ * independent readers behind: main() (`reconciliation.rounds.flatMap(...)`) and the local rehearsal
+ * (scripts/rehearse-corpus-pipeline.mjs). Both threw "Cannot read properties of undefined (reading
+ * 'flatMap')" AFTER the whole generation had been acquired, so every corpus-publish run died at its
+ * last line and the rehearsal meant to catch that died at the same place. Every reader now goes
+ * through here, and a result without an `attempts` array fails by name instead of by TypeError.
+ */
+export function summarizeReconciliation(reconciliation) {
+  const attempts = reconciliation?.attempts;
+  if (!Array.isArray(attempts)) {
+    fail(`reconciliation result has no attempts array (keys: ${Object.keys(reconciliation || {}).join(', ') || 'none'}); `
+      + 'acquireSealedGeneration returns { observation, coverage, attempts, ... }');
+  }
+  const across = (field) => attempts.flatMap((attempt) => attempt?.[field] || []);
+  return {
+    attempts: attempts.length,
+    observationSha256: reconciliation.observation?.observationSha256 ?? null,
+    plan: across('plan'),
+    refreshed: across('refreshed'),
+    pruned: across('pruned'),
+    rebuilt: across('rebuilt'),
+  };
+}
+
 function defaultRun(command, args, options = {}) {
   return spawnSync(command, args, { encoding: 'utf8', ...options });
 }
@@ -668,7 +734,8 @@ export async function reconcileAndPrepareCorpusCandidate({ assetsDir, workspaceD
   owner = 'ruvnet', builderSha, candidateDir, receiptFile, coverageFile, bootstrapIdentity = null, maxAttempts = 3,
   reconcile = (options) => acquireCorpusGeneration(options),
   normalizeUpdaters = normalizeUpdaterManifest,
-  accuracyOracleFile = null, accuracyStores = null, accuracySample = null, accuracyTimeoutMs = null,
+  accuracyOracleFile = null, accuracyStores = null, accuracySample = null, accuracySamplePerPartition = null,
+  accuracyTimeoutMs = null,
   prepare = prepareCorpusCandidate } = {}) {
   const finalized = await reconcile({ owner, assetsDir, workspaceDir, root, maxAttempts });
   // Every shipped repository store needs a complete updater entry, and a seed that predates the
@@ -680,7 +747,7 @@ export async function reconcileAndPrepareCorpusCandidate({ assetsDir, workspaceD
   const updaters = normalizeUpdaters({
     assetsDir,
     coverage: finalized.coverage,
-    refreshedStores: (finalized.attempts || []).flatMap((a) => (a.refreshed || []).map((r) => r?.store || r)).filter(Boolean),
+    refreshedStores: summarizeReconciliation(finalized).refreshed.map((r) => r?.store || r).filter(Boolean),
     seedIdentity: bootstrapIdentity,
   });
   if (updaters.missing?.length) {
@@ -691,7 +758,7 @@ export async function reconcileAndPrepareCorpusCandidate({ assetsDir, workspaceD
   const candidate = await prepare({
     root, assetsDir, builderSha, candidateDir, receiptFile, coverageFile, bootstrapIdentity,
     coverage: finalized.coverage,
-    accuracyOracleFile, accuracyStores, accuracySample, accuracyTimeoutMs,
+    accuracyOracleFile, accuracyStores, accuracySample, accuracySamplePerPartition, accuracyTimeoutMs,
   });
   return { reconciliation: finalized, updaters, candidate };
 }
@@ -707,7 +774,11 @@ export function prepareCorpusCandidate({
   coverage,
   accuracyOracleFile = null,
   accuracyStores = null,
+  // ADR-0091 D2: a whole-oracle, deterministic question sample (retrieval-accuracy.mjs
+  // --sample-questions). `accuracySamplePerPartition` is the older first-k-per-partition bound; its
+  // floor is one question per partition (196 x 2 queries, ~27 min hosted), so it cannot meet D2.
   accuracySample = null,
+  accuracySamplePerPartition = null,
   accuracyTimeoutMs = null,
   run = defaultRun,
 }) {
@@ -770,9 +841,14 @@ export function prepareCorpusCandidate({
   const bundleFile = path.join(path.dirname(candidate), `${path.basename(candidate)}.zip`);
   // ADR-086 Step 15: the benchmark runs HERE — after single-pass assembly and before the seal —
   // against the EXTRACTED final archive through the customer query path, never against `assets`.
-  // The report is written detached, beside the archive, and the seal below binds its digest. A
-  // bounded run (--stores/--sample) still writes a report, but it marks itself incomplete and the
-  // seal refuses it, so a bounded measurement can never be presented as a corpus-wide pass.
+  // The report is written detached, beside the archive, and the receipt below binds its digest.
+  // C3 is a non-blocking diagnostic (ADR-086 amendment 2026-09-15): every reader of this report
+  // (corpus-candidate.mjs, release.mjs, corpus-seed.yml) uses readDiagnosticAccuracyReport, which
+  // checks only its schema and its binding to this archive, oracle and generator -- never whether
+  // coverage is complete. So a bounded run (--stores/--sample/--sample-questions) seals exactly like
+  // a full one; it marks itself `coverage.complete: false`, and only the retained strict reader
+  // (validateAccuracyReport, the re-arm path) would refuse it. corpus-seed.yml runs a question
+  // sample (ADR-0091 D2) because the full run cost 82 minutes on a hosted runner.
   const accuracyReportFile = `${bundleFile}.accuracy.json`;
   // A stale leftover report from a prior run must never be mistaken for a fresh measurement of
   // THIS bundle -- delete it before invoking the script so only a report the script just wrote
@@ -781,7 +857,8 @@ export function prepareCorpusCandidate({
   const accuracyResult = run(process.execPath, [accuracyScript, '--bundle', bundleFile,
     '--oracle', accuracyOracle, '--out', accuracyReportFile,
     ...(accuracyStores != null ? ['--stores', String(accuracyStores)] : []),
-    ...(accuracySample != null ? ['--sample', String(accuracySample)] : []),
+    ...(accuracySample != null ? ['--sample-questions', String(accuracySample)] : []),
+    ...(accuracySamplePerPartition != null ? ['--sample', String(accuracySamplePerPartition)] : []),
     ...(accuracyTimeoutMs != null ? ['--timeout-ms', String(accuracyTimeoutMs)] : [])],
   { stdio: 'inherit' }) || {};
   // C3 was demoted to a non-blocking diagnostic on 2026-09-15 (commit a20727b7, ADR-086
@@ -833,7 +910,10 @@ function arg(argv, name, fallback = null) {
   return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
 }
 
-export async function main(argv = process.argv.slice(2)) {
+// The two injectable seams exist so a test can drive main() end to end (ADR-0091 D1): nothing
+// called main() before, which is how its last line stayed broken for weeks. Production passes neither.
+export async function main(argv = process.argv.slice(2), {
+  reconcileAndPrepare = reconcileAndPrepareCorpusCandidate, stdout = process.stdout, stderr = process.stderr } = {}) {
   const root = path.resolve(arg(argv, '--root', DEFAULT_ROOT));
   const archiveFile = path.resolve(arg(argv, '--seed-archive', ''));
   const seedTag = arg(argv, '--seed-tag');
@@ -846,10 +926,14 @@ export async function main(argv = process.argv.slice(2)) {
   const builderSha = String(arg(argv, '--builder-sha', '')).toLowerCase();
   const owner = arg(argv, '--owner', 'ruvnet');
   const accuracyOracleFile = path.resolve(arg(argv, '--accuracy-oracle', path.join(root, 'data', 'retrieval-accuracy-oracle.json')));
-  // Bounded measurement is explicit and opt-in. It never yields a sealable candidate — the seal
-  // refuses an incomplete report — so these flags exist for measuring, not for shipping.
+  // Bounded measurement is explicit and opt-in; omit every flag below for the full C3 audit.
+  // `--accuracy-sample <n>` measures n oracle questions in total (both query modes), chosen
+  // deterministically -- what corpus-seed.yml passes (ADR-0091 D2). A bounded report still seals,
+  // because C3 is a diagnostic and its readers check binding, not completeness.
   const accuracyStores = arg(argv, '--accuracy-stores') ? Number(arg(argv, '--accuracy-stores')) : null;
   const accuracySample = arg(argv, '--accuracy-sample') ? Number(arg(argv, '--accuracy-sample')) : null;
+  const accuracySamplePerPartition = arg(argv, '--accuracy-sample-per-partition')
+    ? Number(arg(argv, '--accuracy-sample-per-partition')) : null;
   const accuracyTimeoutMs = arg(argv, '--accuracy-timeout-ms') ? Number(arg(argv, '--accuracy-timeout-ms')) : null;
 
   const bootstrap = assertBootstrapIdentity({ archiveFile, tag: seedTag, sha256: seedSha256, allowPinnedTag: process.argv.includes('--allow-pinned-seed-tag') });
@@ -857,19 +941,29 @@ export async function main(argv = process.argv.slice(2)) {
   fs.mkdirSync(path.dirname(assetsDir), { recursive: true });
   const extractParent = fs.mkdtempSync(path.join(path.dirname(assetsDir), '.corpus-seed-extract-'));
   await extractZip(archiveFile, extractParent);
-  normalizeExtractedCorpus({ extractedDir: extractParent, assetsDir });
+  try {
+    normalizeExtractedCorpus({ extractedDir: extractParent, assetsDir });
+  } catch (error) {
+    if (!(error instanceof SeedLedgerIncompatibleError)) throw error;
+    // Nothing was moved; leave --assets exactly as absent/empty as it was so the one bootstrap retry
+    // in corpus-seed.yml can reuse the same path. A distinct exit code, never a generic failure.
+    fs.rmSync(extractParent, { recursive: true, force: true });
+    stderr.write(`${error.message}\n[corpus-reconcile] seed ${seedTag} cannot be consumed by this runtime; `
+      + `exiting ${SEED_LEDGER_INCOMPATIBLE_EXIT} so the caller can fall back to the committed bootstrap seed\n`);
+    return SEED_LEDGER_INCOMPATIBLE_EXIT;
+  }
   const privateFence = path.join(root, 'kb', 'PRIVATE-STORES.json');
   if (!fs.existsSync(privateFence)) fail(`canonical private-store fence missing (${privateFence})`);
   fs.copyFileSync(privateFence, path.join(assetsDir, 'PRIVATE-STORES.json'), fs.constants.COPYFILE_EXCL);
   fs.rmSync(extractParent, { recursive: true, force: true });
   syncCorpusInputs({ root, assetsDir });
   const bootstrapIdentity = { tag: bootstrap.tag, sha256: bootstrap.sha256, privateFenceEvidence: seedPrivateFenceEvidence(assetsDir) };
-  const { reconciliation, candidate } = await reconcileAndPrepareCorpusCandidate({
+  const { reconciliation, candidate } = await reconcileAndPrepare({
     assetsDir, workspaceDir, root, owner, builderSha, candidateDir, receiptFile, coverageFile, bootstrapIdentity,
-    accuracyOracleFile, accuracyStores, accuracySample, accuracyTimeoutMs,
+    accuracyOracleFile, accuracyStores, accuracySample, accuracySamplePerPartition, accuracyTimeoutMs,
   });
-  const plan = reconciliation.rounds.flatMap((round) => round.plan);
-  process.stdout.write(`${JSON.stringify({ ok: true, seedTag, seedSha256, plan, reconciliation, ...candidate }, null, 2)}\n`);
+  const { plan } = summarizeReconciliation(reconciliation);
+  stdout.write(`${JSON.stringify({ ok: true, seedTag, seedSha256, plan, reconciliation, ...candidate }, null, 2)}\n`);
   return 0;
 }