ruvnet-brain 4.3.34 → 4.3.36

package/scripts/corpus-dispatch-decision.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// scripts/corpus-dispatch-decision.mjs — the ONE decision the nightly corpus dispatcher makes.
+//
+// WHY A MODULE (2026-09-29 nightly redesign). The decision used to live as bash in
+// corpus-nightly-dispatch.yml and compared the approved runtime against main HEAD: whenever main
+// carried a commit newer than the newest install-verified release -- which under "every main commit
+// is a release" is exactly the window between a code release landing and its verification finishing,
+// and forever if that verification failed -- the nightly stood down, silently. The corpus is built at
+// the APPROVED runtime's own source, so main HEAD is irrelevant to it and is no longer consulted.
+//
+// decide() is pure and returns one of three verdicts:
+//   arm         dispatch protected-release mode=corpus at the approved release's sourceSha
+//   stand-down  a correct, quiet non-event (kill switch off, newest release not yet verified, or an
+//               approved runtime older than the first release whose pipeline understands this workflow)
+//   fail        evidence is present but does not hold -- loud, never a silent skip
+//
+// minPipelineVersion: the dispatched workflow text is always main's, but the scripts it runs come from
+// the approved release's checkout. A runtime older than MIN_PIPELINE_VERSION does not know the flags
+// the new workflow passes (--approved-tag, --no-change-out), so the nightly stands down rather than
+// let new workflow text drive old scripts.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const MIN_PIPELINE_VERSION = '4.3.36'; // sync-version-ignore: a fixed pipeline floor, not the current version
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const HEX40 = /^[0-9a-f]{40}$/;
+const CODE_TAG = /^v\d+\.\d+\.\d+$/;
+// scripts/approved-runtime.mjs names the release it refused: "code release vX.Y.Z (the newest) carries ...".
+const REFUSED_NEWEST = /code release (v\d+\.\d+\.\d+) \(the newest\)/;
+
+/** -1 / 0 / 1; throws on anything that is not plain x.y.z. */
+export function compareVersions(left, right) {
+  const a = SEMVER.exec(String(left || ''));
+  const b = SEMVER.exec(String(right || ''));
+  if (!a || !b) throw new Error(`cannot compare versions ${JSON.stringify(left)} and ${JSON.stringify(right)}`);
+  for (let i = 1; i <= 3; i += 1) {
+    const delta = Number(a[i]) - Number(b[i]);
+    if (delta) return Math.sign(delta);
+  }
+  return 0;
+}
+
+/** The owner's kill switch: CORPUS_NIGHTLY reading `off` (any case, surrounding space ignored). */
+export function killSwitchOff(nightlyVar) {
+  return String(nightlyVar ?? '').trim().toLowerCase() === 'off';
+}
+
+/**
+ * @param nightlyVar   repository variable CORPUS_NIGHTLY (armed unless it reads `off`, any case; the owner's
+ *                     approval of the code release is the consent)
+ * @param resolution   { status: 'resolved', release: {tag, version, sourceSha} }
+ *                   | { status: 'not-yet-verified' } | { status: 'invalid', reason }
+ */
+export function decide({ nightlyVar, resolution, minPipelineVersion = MIN_PIPELINE_VERSION } = {}) {
+  if (killSwitchOff(nightlyVar)) {
+    return { verdict: 'stand-down', reason: 'repository variable CORPUS_NIGHTLY is off (the owner kill switch)' };
+  }
+  if (resolution?.status === 'not-yet-verified') {
+    return { verdict: 'stand-down', reason: 'the newest code release has not reached install-verified yet (no aggregate)' };
+  }
+  if (resolution?.status === 'invalid' && CODE_TAG.test(String(resolution.tag || ''))
+    && compareVersions(resolution.tag.slice(1), minPipelineVersion) < 0) {
+    // VERSION SKEW, not tampering (found 2026-09-29): this checkout's verifier is a newer generation
+    // than the newest release's aggregate (e.g. D7's retired-fixture denominator), so it cannot judge
+    // it. A runtime below the floor would stand down even if it verified, so standing down loses
+    // nothing -- and an aggregate that claims a runtime AT or above the floor still fails loud below.
+    return { verdict: 'stand-down', reason: `the newest code release ${resolution.tag} predates ${minPipelineVersion}; `
+      + `its install evidence is not judged by this pipeline (${resolution.reason || 'unverifiable here'})` };
+  }
+  if (resolution?.status !== 'resolved') {
+    return { verdict: 'fail', reason: `the newest code release carries install-verification evidence that does not hold: ${resolution?.reason || 'unknown resolution'}` };
+  }
+  const { tag, version, sourceSha } = resolution.release || {};
+  if (!SEMVER.test(String(version || '')) || tag !== `v${version}` || !HEX40.test(String(sourceSha || ''))) {
+    return { verdict: 'fail', reason: `resolved release identity is malformed (${JSON.stringify(resolution.release || null)})` };
+  }
+  if (compareVersions(version, minPipelineVersion) < 0) {
+    return { verdict: 'stand-down', reason: `approved runtime ${tag} predates ${minPipelineVersion}, the first release whose pipeline this workflow can drive` };
+  }
+  return { verdict: 'arm', reason: `building the corpus at approved runtime ${tag} @ ${sourceSha}`, tag, version, sourceSha };
+}
+
+/** approved-runtime.mjs --resolve's exit status + stdout (+ stderr, naming a refused release) -> a resolution. */
+export function resolutionFrom({ status, stdout, stderr = '' }) {
+  if (String(status) === '3') return { status: 'not-yet-verified' };
+  if (String(status) !== '0') {
+    const tag = REFUSED_NEWEST.exec(String(stderr))?.[1] ?? null;
+    const detail = String(stderr).split(': ').slice(-1)[0].trim().slice(0, 300);
+    return { status: 'invalid', tag, reason: `approved-runtime.mjs --resolve exited ${status}${detail ? ` (${detail})` : ''}` };
+  }
+  try {
+    const release = JSON.parse(String(stdout || ''));
+    return { status: 'resolved', release };
+  } catch (error) {
+    return { status: 'invalid', reason: `approved-runtime.mjs --resolve printed no release (${error.message})` };
+  }
+}
+
+const arg = (argv, name) => {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : undefined;
+};
+
+/**
+ * CLI: --nightly <value> --resolve-status <n|skipped> --release <file> [--resolve-stderr <file>]
+ *      --github-output <file>. Exit 1 only on `fail`.
+ *      --is-off <value>  prints true|false (lets the workflow skip the ~555 MB resolve when the switch is off)
+ */
+export function main(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  if (argv.includes('--is-off')) {
+    stdout.write(`${killSwitchOff(arg(argv, '--is-off'))}\n`);
+    return 0;
+  }
+  const nightlyVar = arg(argv, '--nightly') ?? '';
+  const status = arg(argv, '--resolve-status');
+  const releaseFile = arg(argv, '--release');
+  const stderrFile = arg(argv, '--resolve-stderr');
+  const githubOutput = arg(argv, '--github-output');
+  const resolution = status === 'skipped' ? null
+    : resolutionFrom({ status,
+      stdout: releaseFile && fs.existsSync(releaseFile) ? fs.readFileSync(releaseFile, 'utf8') : '',
+      stderr: stderrFile && fs.existsSync(stderrFile) ? fs.readFileSync(stderrFile, 'utf8') : '' });
+  const decision = decide({ nightlyVar, resolution });
+  const lines = decision.verdict === 'arm'
+    ? ['armed=true', `approved_sha=${decision.sourceSha}`, `approved_version=${decision.version}`, `approved_tag=${decision.tag}`]
+    : ['armed=false'];
+  lines.push(`verdict=${decision.verdict}`);
+  if (githubOutput) fs.appendFileSync(path.resolve(githubOutput), `${lines.join('\n')}\n`);
+  const annotation = decision.verdict === 'fail' ? '::error::' : '::notice::';
+  stdout.write(`${annotation}corpus-nightly-dispatch ${decision.verdict}: ${decision.reason}\n`);
+  return decision.verdict === 'fail' ? 1 : 0;
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  process.exitCode = main();
+}

package/scripts/corpus-next-seed.mjs

@@ -11,27 +11,56 @@
 // 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).
+//
+// ADR-0091 D6: --require-coverage is the CODE-RELEASE mode (ci.yml's release-qe and warm-brain jobs,
+// and release.mjs's publish-time re-check). A code release assembles single-pass from the
+// generation's sealed coverage, so a generation that did not publish its coverage sidecar
+// (CORPUS-COVERAGE.json + coverage-receipt.json, D6.2) -- every generation published before D6 --
+// is skipped as incompatible FOR THAT PURPOSE, with its reason. It remains a valid nightly seed:
+// without the flag nothing about the nightly's selection changes.
 //
 // Usage:
-//   node scripts/corpus-next-seed.mjs --repo owner/name [--pin data/approved-runtime.json]
-//                                     [--bootstrap data/corpus-seed.json] [--out <file>]
+//   node scripts/corpus-next-seed.mjs --repo owner/name [--runtime-root <source tree>]
+//                                     [--bootstrap data/corpus-seed.json] [--require-coverage] [--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';
+import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, bindCoverageToReceipt, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HEX64 = /^[0-9a-f]{64}$/;
@@ -39,6 +68,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,103 +97,215 @@ 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);
+  const fixture = recall.loadFixture(fixtureFile || path.join(root, recall.DEFAULT_FIXTURE_FILE));
+  return {
+    runtimeRoot: root,
+    model,
+    dimensions,
+    fixtureSha256: fixture.fixtureSha256,
+    fixtureStores: fixture.questions.map((question) => question.store),
+    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, requireCoverage = false }) {
+  // `indeterminate` marks a rejection that says nothing about the release itself -- the network or
+  // `gh` failed. A publish-time re-check (ADR-0091 D6.6) must not read one as "no newer generation".
+  const reject = (reason, { indeterminate = false } = {}) => {
+    rejected.push({ tag, reason, ...(indeterminate ? { indeterminate: true } : {}) });
+    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})`, { indeterminate: true });
   }
+  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 (requireCoverage && [COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET].some((name) => named(name).length !== 1)) {
+    return reject(`incompatible for a code release: no coverage sidecar (${COVERAGE_ASSET} + ${COVERAGE_RECEIPT_ASSET}; `
+      + 'published before ADR-0091 D6.2)');
   }
+  const archive = named(ARCHIVE_ASSET)[0];
+  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', { indeterminate: true });
     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');
     }
-    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 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}`);
+    }
+
+    // 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', { indeterminate: true });
+    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 claimed = null;
+    try { claimed = JSON.parse(fs.readFileSync(recallFile, 'utf8')); } catch { /* the reader names it below */ }
+    const claimedFixture = claimed?.fixture?.sha256 ?? null;
+    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)}`);
+    }
+    // ADR-0091 D7.3: a report that claims retired questions is verified against the generation's own
+    // sealed coverage (its D6.2 sidecar), recomputed by the reader -- in the nightly mode too, or one
+    // retirement would push every night onto the bootstrap. No sidecar means the claim is unverifiable,
+    // and the generation is skipped.
+    const claimsRetirement = claimed?.retirement !== undefined;
+    if (claimsRetirement && !requireCoverage && [COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET].some((name) => named(name).length !== 1)) {
+      return reject('incompatible: recall report claims retired question(s) but the generation published no coverage sidecar '
+        + `(${COVERAGE_ASSET} + ${COVERAGE_RECEIPT_ASSET}) to verify them against`);
+    }
+
+    // D6.2 -- the code-release mode's extra check, from two more small files: the sidecar must name
+    // THIS generation, bind THESE coverage bytes, and the coverage must describe this receipt's stores.
+    let coverage = null;
+    let coverageBytes = null;
+    if (requireCoverage || claimsRetirement) {
+      const sidecarFile = download(run, { repo, tag, pattern: COVERAGE_RECEIPT_ASSET, dir: scratch });
+      const coverageFile = sidecarFile && download(run, { repo, tag, pattern: COVERAGE_ASSET, dir: scratch });
+      if (!sidecarFile || !coverageFile) return reject('unverified: coverage sidecar could not be downloaded', { indeterminate: true });
+      try {
+        coverageBytes = fs.readFileSync(coverageFile);
+        const verified = verifyCoverageSidecar({ sidecar: JSON.parse(fs.readFileSync(sidecarFile, 'utf8')), coverageBytes,
+          generationTag: tag, archiveSha256: digest, archiveBytes: archive.size });
+        bindCoverageToReceipt({ coverage: verified.coverage, receipt });
+        coverage = { asset: COVERAGE_ASSET, sha256: sha256Of(coverageFile), bytes: coverageBytes.length,
+          receiptAsset: COVERAGE_RECEIPT_ASSET, receiptSha256: sha256Of(sidecarFile), degraded: verified.degraded };
+      } catch (error) {
+        return reject(`unverified: coverage sidecar does not bind this generation (${error.message})`);
+      }
+    }
+
+    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,
+        // Ignored by a pre-D7 reader, which then fails closed on a retirement-bearing report's totals.
+        coverageBytes,
+        ...(profile.fixtureStores ? { fixtureStores: profile.fixtureStores } : {}),
+      });
+    } catch (error) {
+      return reject(`incompatible: recall report fails this runtime's reader (${error.message})`);
+    }
+
     return {
       origin: 'published-generation',
       tag,
       asset: ARCHIVE_ASSET,
       sha256: digest,
       bytes: archive.size,
+      // The nightly descriptor keeps its pre-D7 shape even when a retirement claim fetched the coverage.
+      ...(coverage && requireCoverage ? { coverage } : {}),
       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, requireCoverage = false,
 } = {}) {
   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 {
     listed = ghJson(run, ['release', 'list', '--repo', repo, '--limit', String(limit), '--json', 'tagName,isDraft,createdAt']) || [];
   } catch (error) {
-    rejected.push({ tag: null, reason: `release list failed (${error.message})` });
+    rejected.push({ tag: null, reason: `release list failed (${error.message})`, indeterminate: true });
   }
 
   // Every corpus-shaped tag that is NOT usable gets an explicit reason. A silently skipped row is
@@ -174,9 +322,15 @@ 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,
+      requireCoverage });
+    if (resolved) return { seed: resolved, rejected, judged: judged.length, expects };
   }
 
   return {
@@ -190,36 +344,60 @@ 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),
+      requireCoverage: argv.includes('--require-coverage'),
+      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;
+  });
 }