ruvnet-brain 4.3.21 → 4.3.25

package/scripts/release-transaction-provider.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { canonicalJson } from './coverage-integrity.mjs';
+import { isCorpusReleaseTag, latestCodeReleaseTag } from './release-channel-kind.mjs';
 import {
   pollObservation, RECEIPT_PREFIX, receiptDisposition, transactionIdFor,
 } from './release-transaction.mjs';
@@ -16,6 +17,10 @@ const command = (name, args, options = {}) => execFileSync(name, args, {
   encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000, ...options,
 }).trim();
 const json = (name, args, options) => JSON.parse(command(name, args, options));
+// ADR-086 S1: `releases/latest` is the customer download pointer and is a corpus generation on any
+// night a corpus round shipped. Every question this provider asks is about the CODE generation, so
+// it must resolve the latest CODE release rather than read a pointer that now answers differently.
+const latestCodeTag = () => latestCodeReleaseTag(json('gh', ['api', `repos/${REPO}/releases?per_page=30`]));
 const maybe = (callback, fallback = null) => {
   try { return callback(); } catch { return fallback; }
 };
@@ -216,7 +221,7 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
         }
       }
       const npmLatest = command('npm', ['view', `${PACKAGE}@latest`, 'version']);
-      const githubLatest = json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name;
+      const githubLatest = latestCodeTag();
       const legacySettled = [];
       const pending = [];
       for (const { receipt, release } of latestByTransaction.values()) {
@@ -257,7 +262,7 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
     async observeSnapshot(identity, draft = activeDraft, { forceAssets = false } = {}) {
       try {
         const release = draft?.id ? hydratedRelease(releaseById(draft.id)) : null;
-        const latestTag = json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name;
+        const latestTag = latestCodeTag();
         const candidate = maybe(() => json('npm', ['view', `${PACKAGE}@candidate-v${identity.version}`, '--json']), null);
         const exactVersion = maybe(() => json('npm', ['view', `${PACKAGE}@${identity.version}`, '--json']), null);
         const latestVersion = command('npm', ['view', `${PACKAGE}@latest`, 'version']);
@@ -409,7 +414,10 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
 
     async observeGithub(identity) {
       const release = json('gh', ['api', `repos/${REPO}/releases/tags/${identity.tag}`]);
-      const latest = maybe(() => json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name, null);
+      // "Is this release the current CODE generation", not "does it hold the latest pointer". Once a
+      // corpus generation takes the pointer — which is the designed steady state — a genuinely
+      // published code release would otherwise start observing itself as no longer latest.
+      const latest = maybe(() => latestCodeTag(), null);
       return { tag: release.tag_name, sha: tagSha(identity.tag, root), latest: latest === identity.tag };
     },
 
@@ -424,14 +432,23 @@ export function liveReleaseProvider({ root = process.cwd() } = {}) {
       return { version: command('npm', ['view', `${PACKAGE}@latest`, 'version']) };
     },
     async makeGithubLatest(draft, identity, expectedPrior) {
-      const current = json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name;
+      // The prior-generation check is about the CODE lineage: it exists to catch "someone promoted a
+      // different product generation while this transaction was in flight". A corpus generation
+      // legitimately holding `releases/latest` is NOT that — it is the designed steady state between
+      // code releases — so the comparison is made against the latest CODE release, and the pointer's
+      // own kind is recorded rather than treated as a conflict.
+      const pointer = json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name;
+      const current = latestCodeTag();
       if (current !== expectedPrior && current !== identity.tag) {
-        throw new Error(`refusing GitHub promotion: latest is ${current}, expected ${expectedPrior}`);
+        throw new Error(`refusing GitHub promotion: latest code release is ${current}, expected ${expectedPrior}`);
+      }
+      if (isCorpusReleaseTag(pointer)) {
+        process.stdout.write(`[release] promoting over corpus generation ${pointer} — the code bundle carries its own corpus\n`);
       }
       command('gh', ['api', '-X', 'PATCH', `repos/${REPO}/releases/${draft.id}`, '-f', 'make_latest=true']);
     },
     async observeGithubLatest() {
-      return { tag: json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name };
+      return { tag: latestCodeTag() };
     },
     async restoreNpmLatest(prior, expected) {
       const current = command('npm', ['view', `${PACKAGE}@latest`, 'version']);

package/scripts/release.mjs

@@ -35,6 +35,29 @@ import { materializePublicationHandoff, resolvePublicationHandoffPaths } from '.
 import { liveReleaseProvider } from './release-transaction-provider.mjs';
 import { stagedHostVerifier } from './staged-host-verifier.mjs';
 import { verifyPayload } from './release-payload.mjs';
+import { verifyCorpusReceipt } from './corpus-candidate.mjs';
+import { readDiagnosticAccuracyReport } from './oracle/retrieval-accuracy.mjs';
+import { loadFixture, readRecallReport } from './oracle/repo-recall.mjs';
+
+/**
+ * The measured retrieval numbers, stated in the release notes themselves rather than left behind a
+ * digest. Both halves go in together on purpose: the number that qualified the release, and the one
+ * it did NOT meet. A reader who sees only the first would reasonably assume the second was fine.
+ */
+const recallNotes = (receipt) => {
+  const r = receipt.recallSummary;
+  if (!r) return [];
+  return [
+    `Retrieval (blocking): ${r.repositoriesAnswering}/${r.questions} repositories answer a real question`
+      + ` about themselves from their own content; ${r.exactFileTop5}/${r.questions} return the exact`
+      + ` labeled file in the top 5 (floor ${r.floor}).`,
+    'NOT measured: generated-answer correctness, citation support, or unscoped whole-corpus discovery.',
+    `ADR-086 C3 was NOT met and is NOT claimed — its measurement ships as ${receipt.accuracyReport.file}`
+      + ' for inspection.',
+  ];
+};
+import { verifyBundle } from './verify-bundle.mjs';
+import { CORPUS_GENERATION_FIELD, evaluateCorpusPromotion } from './corpus-promotion.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const PUBLISH = process.argv.includes('--publish');
@@ -83,7 +106,7 @@ function corpusFailure(message) {
   throw new Error(`[corpus-seed] ${message}`);
 }
 
-export function runProtectedCorpusSeed({
+export async function runProtectedCorpusSeed({
   argv = process.argv.slice(2),
   env = process.env,
   root = ROOT,
@@ -94,6 +117,13 @@ export function runProtectedCorpusSeed({
     corpusFailure(environmentFailures.join('; '));
   }
 
+  // The corpus route may never enter product publication. This is belt to the workflow's braces: the
+  // corpus job binds an environment that holds no NPM_TOKEN at all, so npm is unreachable from it by
+  // construction; this refuses the combined invocation outright so the two modes can never share one
+  // process even if a future workflow edit put them in the same job.
+  if (argv.includes('--publish')) corpusFailure('--corpus-seed cannot be combined with --publish; corpus routing must never enter product publication');
+  const promoteLatest = argv.includes('--promote-latest');
+
   const tag = cliArg(argv, '--corpus-tag');
   const bundleFile = cliArg(argv, '--corpus-bundle');
   const receiptFile = cliArg(argv, '--corpus-receipt');
@@ -130,11 +160,20 @@ export function runProtectedCorpusSeed({
     corpusFailure('target must exactly equal HEAD, GITHUB_SHA, and the corpus receipt builderSourceSha');
   }
 
-  const boundaryIdentities = [receipt.privateFence, receipt.eligibilityPolicy, receipt.generationLedger];
+  // Schema 3 (ADR-086 Step 15 / A6): the receipt binds the full provenance closure shipped INSIDE
+  // the sealed archive (ARCHIVE-MANIFEST.json, PRIVATE-STORES.json, RVF-GENERATIONS.json,
+  // SOURCE.json) AND the detached, digest-bound retrieval-accuracy report that measured this exact
+  // archive. Schema 2 is refused outright: a schema-2 seed carries no accuracy binding, so it is
+  // UNPUBLISHABLE from here forward and data/corpus-seed.json must be re-pointed at a schema-3 seed
+  // in the same change that publishes one.
+  const boundaryIdentities = [receipt.privateFence, receipt.generationLedger, receipt.sourceManifest, receipt.archiveManifest];
   const storeBindingsValid = Number.isSafeInteger(receipt.storeCount) && receipt.storeCount > 0
     && Array.isArray(receipt.stores) && receipt.stores.length === receipt.storeCount
     && receipt.stores.every((store) => typeof store?.name === 'string' && store.name.length > 0
-      && /^[a-f0-9]{7,64}$/.test(String(store.sourceCommit || ''))
+      && ['repository', 'gist-aggregate', 'derived'].includes(store.kind)
+      && (store.kind === 'repository'
+        ? /^[a-f0-9]{7,64}$/.test(String(store.sourceCommit || ''))
+        : store.sourceCommit === null || /^[a-f0-9]{7,64}$/i.test(String(store.sourceCommit || '')))
       && typeof store.builtUtc === 'string' && Number.isFinite(Date.parse(store.builtUtc))
       && typeof store.model === 'string' && store.model.length > 0
       && Number.isSafeInteger(store.dimensions) && store.dimensions > 0
@@ -146,9 +185,10 @@ export function runProtectedCorpusSeed({
   const generatorFile = path.join(root, 'scripts/corpus-candidate.mjs');
   const generatorValid = fs.existsSync(generatorFile)
     && receipt.generator?.corpusCandidateSha256 === sha256File(generatorFile);
-  if (receipt.schemaVersion !== 1 || receipt.kind !== 'ruvnet-brain-corpus-candidate'
-    || !receipt.createdAt || !receipt.coverageGeneration || !storeBindingsValid || !emptyFailureArrays
+  if (receipt.schemaVersion !== 3 || receipt.kind !== 'ruvnet-brain-corpus-candidate'
+    || !receipt.createdAt || !storeBindingsValid || !emptyFailureArrays
     || !privateExclusionsValid || !boundaryIdentities.every(exactFileIdentity) || !exactFileIdentity(receipt.archive)
+    || !exactFileIdentity(receipt.accuracyReport)
     || !generatorValid
     || receipt.archive.file !== path.basename(bundleFile)) {
     corpusFailure('corpus receipt bindings are incomplete or invalid');
@@ -160,6 +200,98 @@ export function runProtectedCorpusSeed({
   }
   if (digestMatch[1] !== archiveSha256) corpusFailure('corpus tag digest does not match the receipt and archive');
 
+  // ADR-086 Step 15's second binding. The detached accuracy report travels beside the archive; this
+  // proves (a) the file the receipt names is the file present here, byte for byte, (b) the report
+  // was measured against THESE archive bytes, (c) every partition in both query modes passed
+  // 20x>=19x with no timeouts and no bounded sampling, and (d) it was produced by the committed
+  // benchmark against the committed oracle — so a swapped oracle or a patched benchmark is caught
+  // here even though the receipt itself carries only {file, sha256, bytes}.
+  const accuracyReportFile = `${bundleFile}.accuracy.json`;
+  if (receipt.accuracyReport.file !== path.basename(accuracyReportFile)) {
+    corpusFailure('corpus receipt names an accuracy report that is not the one beside this archive');
+  }
+  if (!fs.existsSync(accuracyReportFile) || !fs.statSync(accuracyReportFile).isFile()) {
+    corpusFailure(`detached retrieval-accuracy report missing beside the archive (${path.basename(accuracyReportFile)})`);
+  }
+  if (sha256File(accuracyReportFile) !== receipt.accuracyReport.sha256
+    || fs.statSync(accuracyReportFile).size !== receipt.accuracyReport.bytes) {
+    corpusFailure('detached retrieval-accuracy report bytes do not match the corpus receipt');
+  }
+  const committedOracleFile = path.join(root, 'data/retrieval-accuracy-oracle.json');
+  const accuracyGeneratorFile = path.join(root, 'scripts/oracle/retrieval-accuracy.mjs');
+  if (!fs.existsSync(committedOracleFile)) corpusFailure('committed retrieval-accuracy oracle is missing from the release checkout');
+  if (!fs.existsSync(accuracyGeneratorFile)) corpusFailure('committed retrieval-accuracy benchmark is missing from the release checkout');
+  // The BLOCKING retrieval predicate at publication is the frozen-fixture repo-recall gate, read
+  // through the same module candidate acceptance used so the two can never drift apart. ADR-086's
+  // C3 report still has to exist and still has to be bound to these exact archive bytes — an
+  // unbound diagnostic looks like evidence and is worse than none — but its score no longer refuses
+  // publication. That reduction is declared in docs/adr/0086 and in the published report itself.
+  const archiveIdentity = { file: receipt.archive.file, sha256: archiveSha256, bytes: fs.statSync(bundleFile).size };
+  try {
+    readDiagnosticAccuracyReport({
+      reportFile: accuracyReportFile,
+      archive: archiveIdentity,
+      expectedOracleSha256: sha256File(committedOracleFile),
+      expectedGeneratorSha256: sha256File(accuracyGeneratorFile),
+    });
+  } catch (error) {
+    corpusFailure(`the published C3 diagnostic is not bound to this archive (${error.message})`);
+  }
+  const recallReportFile = `${bundleFile}.recall.json`;
+  if (!fs.existsSync(recallReportFile)) {
+    corpusFailure(`detached repo-recall report missing beside the archive (${path.basename(recallReportFile)})`);
+  }
+  if (!receipt.recallReport
+    || sha256File(recallReportFile) !== receipt.recallReport.sha256
+    || fs.statSync(recallReportFile).size !== receipt.recallReport.bytes) {
+    corpusFailure('detached repo-recall report bytes do not match the corpus receipt');
+  }
+  try {
+    readRecallReport({
+      reportFile: recallReportFile,
+      archive: archiveIdentity,
+      expectedFixtureSha256: loadFixture().fixtureSha256,
+    });
+  } catch (error) {
+    corpusFailure(`retrieval does not qualify this corpus for publication (${error.message})`);
+  }
+
+  // Deep re-verification — moved here 2026-09-13 from the deleted scripts/corpus-seed-publish.mjs
+  // (ADR-085). Everything above proves the receipt is well-FORMED and that the archive's outer
+  // digest matches it; none of it proves the receipt is TRUE. verifyCorpusReceipt re-extracts the
+  // sealed archive and re-derives the entire candidate from its own bytes — per-store file digests,
+  // private-store fence, generation ledger, RVF index audit — and requires canonical equality with
+  // the receipt. A receipt with a single forged store digest passes every check above and fails
+  // here. It runs before any `gh` call so an untrue candidate never reaches the network.
+  try {
+    await verifyCorpusReceipt({
+      receiptFile, bundleFile, accuracyReportFile, recallReportFile, expectedBuilderSha: target, expectedArchiveSha256: archiveSha256,
+    });
+  } catch (error) {
+    corpusFailure(`corpus receipt does not verify against the sealed archive (${error.message})`);
+  }
+
+  // EVERY local proof happens before the first network call. `gh` must never be reached by a
+  // candidate that is already known to be unpublishable — that is the same discipline the deep
+  // verifyCorpusReceipt above follows, and a customer release with an unusable signature is exactly
+  // as unpublishable as an untrue receipt.
+  const signatureFile = `${bundleFile}.sig`;
+  const digestFile = `${bundleFile}.sha256`;
+  const generation = String(receipt.createdAt || '');
+  if (promoteLatest) {
+    for (const [label, file] of [['detached signature', signatureFile], ['sha256 sidecar', digestFile]]) {
+      if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        corpusFailure(`customer corpus promotion requires a ${label} beside the archive (${path.basename(file)} missing) — the updater fails closed without it`);
+      }
+    }
+    // The real verifier, against the trust root that ships inside the npm package. Signing happens in
+    // the workflow with the environment-scoped key; this proves the bytes about to be published
+    // verify with the key kb/forge-update.mjs actually carries.
+    const signature = verifyBundle(bundleFile, signatureFile);
+    if (!signature.ok) corpusFailure(`detached signature does not verify against the shipped trust root (${signature.reason})`);
+    if (!Number.isFinite(Date.parse(generation))) corpusFailure('corpus receipt createdAt is not a readable generation timestamp');
+  }
+
   const viewArgs = ['release', 'view', tag, '--json', 'tagName', '--repo', repo];
   const ghCommand = env.RUVNET_GH_COMMAND || 'gh';
   const ghPrefix = env.RUVNET_GH_SCRIPT ? [env.RUVNET_GH_SCRIPT] : [];
@@ -168,33 +300,136 @@ export function runProtectedCorpusSeed({
   const viewError = String(view.error?.message || view.stderr || view.stdout || '');
   if (!/(release not found|no release found)/i.test(viewError)) corpusFailure(`cannot prove ${tag} is absent (${viewError.trim() || `gh exited ${view.status}`})`);
 
+  const receiptSha256 = sha256File(receiptFile);
+  const gh = (args) => run(ghCommand, [...ghPrefix, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+  if (!promoteLatest) {
+    // BOOTSTRAP/RECOVERY seeds stay exactly as ADR-086's original contract left them: an immutable
+    // prerelease that never touches releases/latest. Dual's C4 resolution (S1) narrows the change to
+    // CUSTOMER releases — "Bootstrap-only releases may remain prereleases."
+    const notes = [
+      'Content-addressed RuvNet Brain corpus seed.',
+      `Archive SHA-256: ${archiveSha256}`,
+      `Receipt SHA-256: ${receiptSha256}`,
+      `Accuracy report SHA-256: ${receipt.accuracyReport.sha256}`,
+      `Recall report SHA-256: ${receipt.recallReport.sha256}`,
+      ...recallNotes(receipt),
+      `Stores: ${receipt.storeCount}`,
+      `Builder source SHA: ${receipt.builderSourceSha}`,
+      'This published prerelease is immutable and must never be replaced.',
+    ].join('\n');
+    // The detached accuracy report ships AS AN ASSET. Without it a downloader holds an archive it
+    // cannot re-verify — "reverify the downloaded final artifact against the measured identity"
+    // requires the measurement to travel with the artifact it measured.
+    const createArgs = [
+      'release', 'create', tag,
+      '--prerelease', '--latest=false',
+      '--target', target,
+      '--repo', repo,
+      '--title', `Immutable corpus seed ${archiveSha256.slice(0, 16)}`,
+      '--notes', notes,
+      bundleFile, receiptFile, accuracyReportFile, recallReportFile,
+    ];
+    const create = gh(createArgs);
+    if (create.error || create.status !== 0) {
+      corpusFailure(`protected corpus publication failed (${String(create.error?.message || create.stderr || create.stdout || '').trim()})`);
+    }
+    return { tag, target, repository: repo, archiveSha256, receiptSha256, promoted: false };
+  }
+
+  // ── CUSTOMER CORPUS RELEASE (ADR-086 step 17 / C4 resolution S1) ───────────────────────────────
+  // The old path was invisible AND unusable to a customer, for two independent reasons, and fixing
+  // only one leaves the channel dead. `--prerelease --latest=false` means kb/forge-update.mjs's
+  // releases/latest poll never sees it; and with no detached .sig the updater fails closed anyway
+  // (kb/forge-update.mjs:1275 fetches `${url}.sig`, :1284-1285 exits 4 when verification fails).
+  // scripts/verify-channels.mjs checks exactly these two things (checks 3 and 4) against the live
+  // endpoints, and is the owner's post-publish acceptance gate.
+  const latestView = gh(['release', 'view', '--json', 'tagName,body', '--repo', repo]);
+  let currentLatest = null;
+  if (!latestView.error && latestView.status === 0) {
+    try { currentLatest = JSON.parse(String(latestView.stdout || 'null')); }
+    catch (error) { corpusFailure(`cannot read the current latest release (${error.message})`); }
+    if (!currentLatest || typeof currentLatest.tagName !== 'string') corpusFailure('current latest release carries no tag name');
+  } else {
+    const latestError = String(latestView.error?.message || latestView.stderr || latestView.stdout || '');
+    if (!/(release not found|no release found)/i.test(latestError)) {
+      corpusFailure(`cannot determine the current latest release (${latestError.trim() || `gh exited ${latestView.status}`})`);
+    }
+  }
+  const promotion = evaluateCorpusPromotion({ tag, generation, currentLatest });
+  if (!promotion.allowed) corpusFailure(promotion.reason);
+
   const notes = [
-    'Content-addressed RuvNet Brain corpus seed.',
+    'RuvNet Brain corpus generation — signed, content-addressed, and promoted to latest.',
+    `${CORPUS_GENERATION_FIELD} ${generation}`,
     `Archive SHA-256: ${archiveSha256}`,
-    `Receipt SHA-256: ${sha256File(receiptFile)}`,
+    `Receipt SHA-256: ${receiptSha256}`,
     `Stores: ${receipt.storeCount}`,
-    `Coverage generation: ${receipt.coverageGeneration}`,
-    'This published prerelease is immutable and must never be replaced.',
+    `Builder source SHA: ${receipt.builderSourceSha}`,
+    `Shipped runtime: ${receipt.archiveManifestReleaseTag}`,
+    ...recallNotes(receipt),
+    'Immutable: this tag is the archive digest and must never be replaced.',
   ].join('\n');
-  const createArgs = [
+
+  // ASSETS COMPLETE BEFORE PROMOTION. `gh release create` uploads assets AFTER the release exists, so
+  // creating a non-draft release directly opens a window in which releases/latest resolves to a
+  // release with no archive — every polling client in that window fails or, worse, half-downloads.
+  // Create as a draft (invisible to releases/latest), prove all four assets landed, and only then
+  // flip draft off and claim latest in one edit.
+  // Both reports ride with every corpus release for the same reason they ride with a seed: a customer
+  // (or the next night's dispatcher) that downloads the archive must be able to reverify it against
+  // the identity it was actually measured under — the blocking recall gate AND the C3 diagnostic it
+  // scored 59.0% on, so nobody has to take either number on trust.
+  const assetFiles = [bundleFile, signatureFile, digestFile, receiptFile, accuracyReportFile, recallReportFile];
+  const create = gh([
     'release', 'create', tag,
-    '--prerelease', '--latest=false',
+    '--draft',
     '--target', target,
     '--repo', repo,
-    '--title', `Immutable corpus seed ${archiveSha256.slice(0, 16)}`,
+    '--title', `RuvNet Brain corpus ${archiveSha256.slice(0, 16)}`,
     '--notes', notes,
-    bundleFile, receiptFile,
-  ];
-  const create = run(ghCommand, [...ghPrefix, ...createArgs], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    ...assetFiles,
+  ]);
   if (create.error || create.status !== 0) {
     corpusFailure(`protected corpus publication failed (${String(create.error?.message || create.stderr || create.stdout || '').trim()})`);
   }
-  return { tag, target, repository: repo, archiveSha256, receiptSha256: sha256File(receiptFile) };
+
+  const expectedAssets = assetFiles.map((file) => path.basename(file)).sort();
+  const draftView = gh(['release', 'view', tag, '--json', 'isDraft,assets', '--repo', repo]);
+  if (draftView.error || draftView.status !== 0) corpusFailure('cannot confirm the draft corpus release before promotion');
+  let draft;
+  try { draft = JSON.parse(String(draftView.stdout || 'null')); }
+  catch (error) { corpusFailure(`cannot read the draft corpus release (${error.message})`); }
+  const uploaded = (draft?.assets || []).filter((asset) => asset?.state === 'uploaded' && Number.isSafeInteger(asset.size) && asset.size > 0);
+  if (draft?.isDraft !== true || JSON.stringify(uploaded.map((asset) => asset.name).sort()) !== JSON.stringify(expectedAssets)) {
+    corpusFailure(`refusing to promote an incomplete corpus release; expected ${expectedAssets.join(', ')} fully uploaded on a draft`);
+  }
+
+  const promote = gh(['release', 'edit', tag, '--repo', repo, '--draft=false', '--latest', '--prerelease=false']);
+  if (promote.error || promote.status !== 0) {
+    corpusFailure(`corpus promotion to latest failed (${String(promote.error?.message || promote.stderr || promote.stdout || '').trim()})`);
+  }
+
+  const finalView = gh(['release', 'view', tag, '--json', 'tagName,isDraft,isLatest,isPrerelease,assets', '--repo', repo]);
+  if (finalView.error || finalView.status !== 0) corpusFailure('cannot confirm the promoted corpus release');
+  let promoted;
+  try { promoted = JSON.parse(String(finalView.stdout || 'null')); }
+  catch (error) { corpusFailure(`cannot read the promoted corpus release (${error.message})`); }
+  const promotedAssets = (promoted?.assets || []).map((asset) => asset?.name).sort();
+  if (promoted?.tagName !== tag || promoted.isDraft !== false || promoted.isLatest !== true
+    || promoted.isPrerelease !== false || JSON.stringify(promotedAssets) !== JSON.stringify(expectedAssets)) {
+    corpusFailure('corpus release did not reach a complete, non-draft, non-prerelease latest state');
+  }
+
+  return {
+    tag, target, repository: repo, archiveSha256, receiptSha256, promoted: true,
+    generation, supersededLatest: currentLatest?.tagName || null,
+  };
 }
 
 if (CORPUS_SEED) {
   try {
-    const result = runProtectedCorpusSeed();
+    const result = await runProtectedCorpusSeed();
     console.log(JSON.stringify({ ok: true, mode: 'corpus-seed', ...result }, null, 2));
   } catch (error) {
     console.error(error.message);

package/scripts/retrieval-canary.mjs

@@ -169,6 +169,72 @@ export function validateRetrievalQueryEvidence(evidence) {
   return evidence;
 }
 
+// An exemption is a RECORDED, EVIDENCED admission that one eligible store's upstream bytes cannot
+// support a source-grounded question — never a bypass. It satisfies the inventory obligation only;
+// buildRetrievalCanaryPlan still demands a row for every eligible store, so an exempted store must
+// also leave the eligible corpus before a canary plan can be sealed. Recording one is a coverage
+// policy decision that someone has to make in the open, which is the entire point.
+export function validateOracleExemptions(exemptions) {
+  if (exemptions === null || exemptions === undefined) return [];
+  if (canonicalJson(Object.keys(exemptions || {}).sort()) !== canonicalJson(['exemptions', 'kind', 'schemaVersion'])
+    || exemptions.schemaVersion !== 1 || exemptions.kind !== 'ruvnet-brain-retrieval-oracle-exemptions'
+    || !Array.isArray(exemptions.exemptions)) {
+    throw new Error('retrieval oracle exemptions are malformed');
+  }
+  for (const row of exemptions.exemptions) {
+    if (canonicalJson(Object.keys(row || {}).sort()) !== canonicalJson(['evidencePaths', 'reason', 'store', 'upstreamSha'])
+      || typeof row.store !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/.test(row.store)
+      || typeof row.reason !== 'string' || row.reason.trim().length < 24
+      || !HEX40.test(String(row.upstreamSha || ''))
+      || !Array.isArray(row.evidencePaths) || row.evidencePaths.length < 1
+      || row.evidencePaths.some((file) => typeof file !== 'string' || !file || path.isAbsolute(file)
+        || file.split(/[\\/]/).includes('..'))) {
+      throw new Error(`retrieval oracle exemption for ${row?.store || '(missing)'} is malformed`);
+    }
+  }
+  const stores = exemptions.exemptions.map((row) => row.store);
+  if (new Set(stores).size !== stores.length) throw new Error('retrieval oracle exemptions name a store twice');
+  return exemptions.exemptions;
+}
+
+// The cheap, standalone form of the denominator gate buildRetrievalCanaryPlan enforces at release
+// time against a 567MB seed. Missing evidence is a FAILURE here, named store by store, seconds after
+// a new repository lands in coverage — not six minutes into release-qe on a runner.
+export function auditOracleCoverage({ coverage, queryEvidence, exemptions = null } = {}) {
+  const checked = validateCoverageLedger(coverage);
+  if (!checked.valid) throw new Error(`coverage ledger is invalid: ${checked.failures.join('; ')}`);
+  validateRetrievalQueryEvidence(queryEvidence);
+  const eligibleRows = coverage.rows.filter((row) => row.kind === 'repository'
+    && row.disposition === 'eligible' && row.status === 'CURRENT');
+  const eligible = ordered(eligibleRows.map(storeOf));
+  if (!eligible.length || new Set(eligible).size !== eligible.length || eligible.some((store) => !store)) {
+    throw new Error('eligible coverage denominator is invalid');
+  }
+  const oracle = new Set(Object.keys(queryEvidence.queries));
+  const exempted = validateOracleExemptions(exemptions);
+  const exemptStores = new Set(exempted.map((row) => row.store));
+  const uncovered = eligible.filter((store) => !oracle.has(store));
+  const missing = uncovered.filter((store) => !exemptStores.has(store));
+  const exempt = uncovered.filter((store) => exemptStores.has(store));
+  const extra = ordered([...oracle].filter((store) => !eligible.includes(store)));
+  const stale = ordered(exempted.map((row) => row.store).filter((store) => !uncovered.includes(store)));
+  const result = { eligible: eligible.length, covered: eligible.length - uncovered.length,
+    missing, exempt, extra, staleExemptions: stale };
+  if (missing.length) {
+    throw new Error(`independent retrieval oracle has no source-grounded row for ${missing.length} of `
+      + `${eligible.length} eligible stores: ${missing.join(', ')}`);
+  }
+  if (extra.length) {
+    throw new Error(`independent retrieval oracle covers ${extra.length} store(s) outside the eligible `
+      + `denominator: ${extra.join(', ')}`);
+  }
+  if (stale.length) {
+    throw new Error(`retrieval oracle exemption is stale for ${stale.join(', ')}; the store is covered `
+      + 'or no longer eligible, so the recorded admission must be removed');
+  }
+  return result;
+}
+
 export function verifyQueryOracleSource(queryEvidence, candidateSourceSha, {
   cwd = process.cwd(), run = spawnSync, allowSquashedSource = false,
 } = {}) {
@@ -600,13 +666,34 @@ export function buildPlanFromFiles({ coverageFile, baselineFile, candidateFile,
   return plan;
 }
 
+export function auditOracleCoverageFromFiles({ coverageFile, oracleFile, exemptionsFile = null,
+  candidateSourceSha = null, cwd = process.cwd() }) {
+  const coverage = JSON.parse(fs.readFileSync(regular(coverageFile, 'coverage'), 'utf8'));
+  const queryEvidence = JSON.parse(fs.readFileSync(regular(oracleFile, 'query oracle'), 'utf8'));
+  const exemptions = exemptionsFile
+    ? JSON.parse(fs.readFileSync(regular(exemptionsFile, 'oracle exemptions'), 'utf8')) : null;
+  const inventory = auditOracleCoverage({ coverage, queryEvidence, exemptions });
+  // The second half of step 7's proof: the oracle's own commit must be a strict ancestor of the
+  // candidate that consumes it, and its tracked bytes must be identical at both.
+  const strictAncestor = candidateSourceSha
+    ? Boolean(verifyQueryOracleSource(queryEvidence, candidateSourceSha, { cwd })) : null;
+  return { ...inventory, oracleSourceCommit: queryEvidence.sourceCommit, strictAncestor };
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
     const argv = process.argv.slice(2);
+    if (argv.includes('--audit')) {
+      const report = auditOracleCoverageFromFiles({ coverageFile: arg(argv, '--coverage'),
+        oracleFile: arg(argv, '--oracle'), exemptionsFile: arg(argv, '--exemptions'),
+        candidateSourceSha: arg(argv, '--candidate-sha'), cwd: arg(argv, '--repo') || process.cwd() });
+      console.log(JSON.stringify({ ok: true, ...report }));
+    } else {
     const plan = buildPlanFromFiles({ coverageFile: arg(argv, '--coverage'), baselineFile: arg(argv, '--baseline'),
       candidateFile: arg(argv, '--candidate'), oracleFile: arg(argv, '--oracle'), assetsDir: arg(argv, '--assets'),
       outFile: arg(argv, '--out'), cwd: arg(argv, '--repo') || process.cwd() });
     console.log(JSON.stringify({ ok: true, planSha256: plan.planSha256, cases: plan.cases.length }));
+    }
   } catch (error) {
     console.error(`[retrieval-canary] ${error.message}`);
     process.exitCode = 1;