ruvnet-brain 4.3.35 → 4.3.37

package/scripts/corpus-store-failure.mjs

@@ -0,0 +1,82 @@
+// ADR-0091 D5 — per-store failure isolation for corpus reconciliation.
+//
+// One store failing to refresh must not abort the whole generation. This module owns the three
+// pure decisions that make that safe, so the reconciler, the rehearsal and the tests share them:
+//
+//   1. WHICH failures are retried. Only transient ones (clone, fetch, runner I/O), exactly once, in a
+//      fresh worker directory. A corpus-qa failure is never retried: the round-trip sample is
+//      deterministic (FNV-1a, corpus-qa.mjs), so a retry re-embeds the whole store to reproduce it.
+//      The class comes from WHERE the worker failed and from forge-refresh's exit status, never
+//      from log text.
+//   2. HOW MANY stores may be carried or missing before the failure is systemic and the generation
+//      must fail loudly: carried + missing <= max(3, 5% of eligible).
+//   3. WHETHER a degraded generation may be published at all. Installed clients judge every bundle
+//      with their INSTALLED validator, and every validator shipped before this change rejects any
+//      non-CURRENT eligible row. ADR-0091 D10 therefore gates degraded publication behind a
+//      transition release plus a 14-day soak; until D10 records that transition, a degraded
+//      generation is built and sealed but never published.
+
+/** kb/forge-refresh.mjs exits with this status when corpus-qa rejected its candidate. */
+export const CORPUS_QA_FAILED_EXIT = 3;
+
+export const FAILURE_CLASS = Object.freeze({
+  TRANSIENT: 'transient',
+  QA: 'qa',
+  BUILD: 'build',
+  INTEGRITY: 'integrity',
+});
+
+/** A worker failure carrying its structured class. `detail` is for logs only, never for shipped rows. */
+export class StoreWorkerError extends Error {
+  constructor({ store, stage, failureClass, detail = '' }) {
+    super(`[corpus-reconcile] ${store}: ${stage} failed (${failureClass})${detail ? ` (${detail})` : ''}`);
+    this.name = 'StoreWorkerError';
+    this.store = store;
+    this.stage = stage;
+    this.failureClass = failureClass;
+  }
+}
+
+export function isRetryable(error) {
+  return error instanceof StoreWorkerError && error.failureClass === FAILURE_CLASS.TRANSIENT;
+}
+
+/**
+ * The shipped, machine-readable reason. Stage and class only: stderr can quote runner paths, and a
+ * coverage row travels to every user.
+ */
+export function failureReason(error) {
+  if (error instanceof StoreWorkerError) return `${error.failureClass}: ${error.stage} failed`;
+  return `${FAILURE_CLASS.INTEGRITY}: worker failed`;
+}
+
+/** Fixed rule: the failure is systemic above max(3, 5% of eligible). */
+export function degradedBound(eligibleCount) {
+  if (!Number.isSafeInteger(eligibleCount) || eligibleCount < 0) throw new Error('eligible count must be a non-negative integer');
+  return Math.max(3, Math.floor(eligibleCount * 0.05));
+}
+
+/**
+ * ADR-0091 D10 owns this value. It stays null until the transition release N (the first release
+ * shipping the tolerant validator while its own coverage is all-CURRENT) has become releases/latest;
+ * D10 then records { version, latestSince } here. Null means no transition: never publish degraded.
+ */
+export const VALIDATOR_TRANSITION = null;
+export const TRANSITION_SOAK_DAYS = 14;
+
+export function degradedPublication({ transition = VALIDATOR_TRANSITION, now = new Date() } = {}) {
+  if (!transition) {
+    return { allowed: false,
+      reason: 'no tolerant-validator transition release is recorded (ADR-0091 D10); installed clients would reject a non-CURRENT row' };
+  }
+  const since = Date.parse(transition.latestSince);
+  if (typeof transition.version !== 'string' || !transition.version || !Number.isFinite(since)) {
+    return { allowed: false, reason: 'the recorded validator transition is malformed' };
+  }
+  const soakEnds = since + TRANSITION_SOAK_DAYS * 24 * 60 * 60 * 1000;
+  if (now.getTime() < soakEnds) {
+    return { allowed: false,
+      reason: `validator transition ${transition.version} soaks until ${new Date(soakEnds).toISOString()} (ADR-0091 D10)` };
+  }
+  return { allowed: true, reason: `validator transition ${transition.version} has soaked ${TRANSITION_SOAK_DAYS} days` };
+}

package/scripts/corpus-watchdog.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// scripts/corpus-watchdog.mjs — is the customer corpus ACTUALLY being refreshed every night?
+//
+// THE FAILURE THIS EXISTS TO END (2026-09-28/29, measured on live run history). The nightly
+// dispatcher `corpus-nightly-dispatch.yml` stood down in ~13 seconds and finished GREEN, night after
+// night, because repository variable CORPUS_NIGHTLY was unset. A green run is not a refreshed corpus:
+// nothing was dispatched, nothing was published, and ntfy-alerts only pages on red. Before that, nine
+// corpus-mode protected-release failures in a row never paged at all (a GITHUB_TOKEN dispatch cannot
+// fire workflow_run). Silence was read as health — the exact failure config/scheduled-jobs.json names:
+// ABSENCE OF EVIDENCE IS FAILURE.
+//
+// So this watchdog does not ask "did a workflow go green?". It asks for EVIDENCE OF AN OUTCOME:
+//   RED      (a) no night ended `published` or `no-change` in the last 48h (catches silent stand-downs)
+//            (b) the newest corpus run of the last 24h failed (or was cancelled / timed out)
+//            (c) the newest vX.Y.Z code release has no VERIFIED public-verification aggregate 24h after
+//                publish, or carries one that does not verify (the nightly cannot arm without it)
+//            (d) any store has been deferred (carried STALE or MISSING) for more than 7 days
+//   WARNING  a superseded or degraded night, a stand-down tonight, an unknown outcome, a long run
+//   GREEN    none of the above
+//
+// Exit code is the contract (same as scripts/github-health-watch.mjs): 0 = GREEN or WARNING,
+// 1 = RED or the evidence could not be gathered. corpus-watchdog.yml runs on a genuine `schedule:`,
+// so its red conclusion fires ntfy-alerts.yml's workflow_run listener — no secret needed here.
+//
+// READ-ONLY. Every gh call below is a list/view/download. It never dispatches, edits, or publishes.
+// Every `--json` field used is one gh 2.101.0 lists for that subcommand (the redesign that created
+// this file exists because release.mjs asked `gh release view` for `isLatest`, which only
+// `gh release list` has); tests/unit/corpus-watchdog.test.mjs pins the lists.
+//
+//   node scripts/corpus-watchdog.mjs [--repo owner/name] [--json] [--now ISO]
+
+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 { CODE_TAG_PATTERN, isCorpusReleaseTag } from './release-channel-kind.mjs';
+import { AGGREGATE_ASSET, SIGNING_PUBLIC_KEY_FILE } from './approved-runtime.mjs';
+import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const RED = 'RED';
+export const WARNING = 'WARNING';
+export const GREEN = 'GREEN';
+export const INFO = 'INFO';
+const HOUR = 3_600_000;
+export const FRESHNESS_WINDOW_MS = 48 * HOUR;
+export const TONIGHT_WINDOW_MS = 24 * HOUR;
+export const AGGREGATE_GRACE_MS = 24 * HOUR;
+export const DEFERRAL_LIMIT_MS = 7 * 24 * HOUR;
+export const LONG_RUN_MS = 8 * HOUR;
+/** protected-release.yml's run-name for a corpus run: `protected-release corpus <dispatch id>`. */
+export const CORPUS_RUN_TITLE = /^protected-release corpus (\S+)$/;
+/** The dispatch id corpus-nightly-dispatch.yml passes: `corpus-<its run id>-<its attempt>`. */
+const DISPATCH_ID = /^corpus-(\d+)-(\d+)$/;
+/** Terminal outcomes a corpus-release-outcome.json may declare in an `outcome` field (design D2). */
+const DECLARED_OUTCOMES = new Set(['published', 'no-change', 'superseded', 'degraded', 'failed']);
+const GOOD_NIGHT = new Set(['published', 'no-change']);
+
+const ms = (iso) => {
+  const t = Date.parse(String(iso ?? ''));
+  return Number.isFinite(t) ? t : null;
+};
+const hours = (delta) => `${(delta / HOUR).toFixed(1)}h`;
+
+/**
+ * What ONE protected-release corpus run proved. Preference order: an explicit `outcome` in the run's
+ * corpus-release-outcome.json, then that record's per-job results, then the run's own job list.
+ * A non-success run conclusion is `failed` unless the record says otherwise (a typed superseded exit
+ * is a warning, not red). A success that shows neither a publish nor a no-change round is `unknown`
+ * — never counted as a good night.
+ */
+export function classifyCorpusRun(run) {
+  if (run?.status !== 'completed') return 'in-progress';
+  const declared = String(run.outcomeRecord?.outcome ?? '').replace('no_change', 'no-change');
+  if (DECLARED_OUTCOMES.has(declared)) return declared;
+  if (run.conclusion !== 'success') return 'failed';
+  const recorded = run.outcomeRecord?.jobs;
+  const byName = new Map((run.jobs || []).map((job) => [job.name, job.conclusion]));
+  const noChange = recorded?.no_change ?? byName.get('corpus-no-change-round');
+  const publish = recorded?.publish ?? byName.get('protected-corpus-publisher');
+  if (noChange === 'success') return 'no-change';
+  if (publish === 'success') return 'published';
+  return 'unknown';
+}
+
+/**
+ * How long each store in the NEWEST generation has been deferred: walk generations newest-first while
+ * the store stays carried/missing; it has been deferred since the oldest generation in that unbroken
+ * run. A generation whose coverage is unknown (published before the D6.2 sidecar, or not fetched)
+ * ends the walk with `lowerBound: true` — the true deferral is at least that long.
+ * `generations`: [{ tag, publishedAt, degraded: { carried, missing } | null }], newest first.
+ */
+export function deferralSince(generations) {
+  const [newest, ...older] = generations || [];
+  if (!newest?.degraded) return [];
+  const stores = [...new Set([...(newest.degraded.carried || []), ...(newest.degraded.missing || [])])].sort();
+  return stores.map((store) => {
+    let since = newest.publishedAt;
+    let lowerBound = true; // until a generation proves the store was NOT deferred, history ran out first
+    for (const generation of older) {
+      if (!generation.degraded) break;
+      if (![...(generation.degraded.carried || []), ...(generation.degraded.missing || [])].includes(store)) { lowerBound = false; break; }
+      since = generation.publishedAt;
+    }
+    return { store, since, lowerBound };
+  });
+}
+
+/**
+ * The pure verdict. `input`:
+ *   corpusReleases  [{ tag, publishedAt }]                           non-draft corpus-sha256-* releases
+ *   corpusRuns      [{ id, title, status, conclusion, createdAt, updatedAt, outcome }]  protected-release corpus runs
+ *   dispatcherRuns  [{ id, attempt, status, conclusion, createdAt }]  corpus-nightly-dispatch runs
+ *   codeRelease     { tag, publishedAt, aggregate: { state: verified|missing|invalid, reason } } | null
+ *   deferral        { observable, reason, newestTag, degraded: {carried, missing}, stores: [{store, since, lowerBound}] }
+ */
+export function judgeCorpusHealth(input, now) {
+  const at = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(at)) throw new Error('judgeCorpusHealth needs a valid `now`');
+  const findings = [];
+  const add = (level, check, detail) => findings.push({ level, check, detail });
+  const age = (iso) => { const t = ms(iso); return t === null || t > at ? null : at - t; };
+  const runs = (input?.corpusRuns || []).map((run) => ({ ...run, outcome: run.outcome ?? classifyCorpusRun(run) }));
+  const dispatchers = input?.dispatcherRuns || [];
+
+  // Dispatcher runs that finished without creating a corpus run: stand-downs (the silent failure).
+  const dispatchedIds = new Set(runs.map((run) => CORPUS_RUN_TITLE.exec(String(run.title || ''))?.[1]).filter(Boolean));
+  const standDowns = dispatchers.filter((d) => d.status === 'completed' && d.conclusion === 'success'
+    && !dispatchedIds.has(`corpus-${d.id}-${d.attempt ?? 1}`));
+
+  // (a) a good night inside the freshness window. Inclusive: exactly 48h old still counts.
+  const evidence = [
+    ...(input?.corpusReleases || []).map((release) => ({ kind: 'published', at: release.publishedAt, ref: release.tag })),
+    ...runs.filter((run) => GOOD_NIGHT.has(run.outcome)).map((run) => ({ kind: run.outcome, at: run.updatedAt, ref: `run ${run.id}` })),
+  ].filter((item) => age(item.at) !== null).sort((a, b) => ms(b.at) - ms(a.at));
+  const lastGoodNight = evidence[0] || null;
+  if (!lastGoodNight || age(lastGoodNight.at) > FRESHNESS_WINDOW_MS) {
+    const recentStandDowns = standDowns.filter((d) => (age(d.createdAt) ?? Infinity) <= FRESHNESS_WINDOW_MS).length;
+    add(RED, 'freshness', `no night ended published or no-change in the last 48h `
+      + `(last: ${lastGoodNight ? `${lastGoodNight.kind} ${lastGoodNight.ref} ${hours(age(lastGoodNight.at))} ago` : 'never observed'}; `
+      + `${recentStandDowns} dispatcher stand-down(s) in the window — a green dispatcher that dispatched nothing is not a refreshed corpus)`);
+  } else {
+    add(GREEN, 'freshness', `${lastGoodNight.kind} ${lastGoodNight.ref} ${hours(age(lastGoodNight.at))} ago`);
+  }
+
+  // (b) tonight: the newest corpus run created in the last 24h.
+  const tonight = runs.filter((run) => (age(run.createdAt) ?? Infinity) <= TONIGHT_WINDOW_MS)
+    .sort((a, b) => ms(b.createdAt) - ms(a.createdAt))[0];
+  const lastDispatcher = dispatchers.filter((d) => (age(d.createdAt) ?? Infinity) <= TONIGHT_WINDOW_MS)
+    .sort((a, b) => ms(b.createdAt) - ms(a.createdAt))[0];
+  if (tonight) {
+    const ref = `corpus run ${tonight.id} (${tonight.title})`;
+    if (tonight.outcome === 'failed') add(RED, 'tonight', `${ref} failed (conclusion ${tonight.conclusion})`);
+    else if (tonight.outcome === 'superseded') add(WARNING, 'tonight', `${ref} was superseded by a newer code release before publish`);
+    else if (tonight.outcome === 'degraded') add(WARNING, 'tonight', `${ref} published a degraded generation`);
+    else if (tonight.outcome === 'unknown') add(WARNING, 'tonight', `${ref} succeeded but shows neither a publish nor a no-change round`);
+    else if (tonight.outcome === 'in-progress') {
+      add((age(tonight.createdAt) ?? 0) > LONG_RUN_MS ? WARNING : INFO, 'tonight', `${ref} still running after ${hours(age(tonight.createdAt) ?? 0)}`);
+    } else add(GREEN, 'tonight', `${ref} ended ${tonight.outcome}`);
+  } else if (!lastDispatcher) {
+    add(WARNING, 'tonight', 'no corpus-nightly-dispatch run in the last 24h (schedule dropped or disabled?)');
+  } else if (lastDispatcher.status === 'completed' && lastDispatcher.conclusion !== 'success') {
+    add(RED, 'tonight', `corpus-nightly-dispatch run ${lastDispatcher.id} concluded ${lastDispatcher.conclusion}`);
+  } else if (standDowns.includes(lastDispatcher)) {
+    add(WARNING, 'tonight', `corpus-nightly-dispatch run ${lastDispatcher.id} stood down: nothing was dispatched `
+      + '(CORPUS_NIGHTLY off, or no install-verified runtime yet)');
+  } else {
+    add(GREEN, 'tonight', `corpus-nightly-dispatch run ${lastDispatcher.id} is ${lastDispatcher.status}`);
+  }
+
+  // (c) the newest code release must reach a verified aggregate within 24h of publish.
+  const code = input?.codeRelease;
+  if (!code) add(RED, 'code-aggregate', 'no published vX.Y.Z code release was found');
+  else if (code.aggregate?.state === 'verified') add(GREEN, 'code-aggregate', `${code.tag} carries a verified PASS aggregate`);
+  else if (code.aggregate?.state === 'invalid') add(RED, 'code-aggregate', `${code.tag} carries an aggregate that does not verify `
+    + `under this checkout's verifier (the one approved-runtime --resolve runs, so the nightly will refuse it too): ${code.aggregate.reason}`);
+  else {
+    const since = age(code.publishedAt);
+    if (since === null || since >= AGGREGATE_GRACE_MS) {
+      add(RED, 'code-aggregate', `${code.tag} was published ${since === null ? 'at an unknown time' : `${hours(since)} ago`} `
+        + 'and still has no public-verification aggregate — the nightly cannot arm');
+    } else add(INFO, 'code-aggregate', `${code.tag} is ${hours(since)} old; aggregate pending (grace 24h)`);
+  }
+
+  // (d) deferred stores. Only observable from a generation that carries the D6.2 coverage sidecar.
+  const deferral = input?.deferral;
+  if (!deferral?.observable) {
+    add(INFO, 'deferral', `not observable: ${deferral?.reason || 'no coverage evidence gathered'}`);
+  } else {
+    const overdue = (deferral.stores || []).filter((row) => (age(row.since) ?? 0) > DEFERRAL_LIMIT_MS);
+    if (overdue.length) {
+      add(RED, 'deferral', `${overdue.length} store(s) deferred more than 7 days: ${overdue.slice(0, 10)
+        .map((row) => `${row.store} (${row.lowerBound ? '≥' : ''}${hours(age(row.since))})`).join(', ')}`);
+    } else add(GREEN, 'deferral', `${(deferral.stores || []).length} deferred store(s), none older than 7 days`);
+    const degraded = [...(deferral.degraded?.carried || []), ...(deferral.degraded?.missing || [])];
+    if (degraded.length) add(WARNING, 'degraded', `${deferral.newestTag} is degraded: ${deferral.degraded.carried.length} carried, ${deferral.degraded.missing.length} missing`);
+  }
+
+  const verdict = findings.some((f) => f.level === RED) ? RED : findings.some((f) => f.level === WARNING) ? WARNING : GREEN;
+  return { verdict, findings, lastGoodNight };
+}
+
+// ── Gathering (read-only gh). Everything above is pure; everything below talks to GitHub. ──────────
+
+function defaultGh(args) {
+  const result = spawnSync(process.env.RUVNET_GH_COMMAND || 'gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 5 * 60_000 });
+  if (result.error || result.status !== 0) {
+    throw new Error(`gh ${args.slice(0, 3).join(' ')} failed: ${String(result.error?.message || result.stderr || `exit ${result.status}`).trim().slice(0, 300)}`);
+  }
+  return result.stdout;
+}
+
+const semver = (tag) => CODE_TAG_PATTERN.test(tag) ? tag.slice(1).split('.').map(Number) : null;
+/** Same selection as scripts/approved-runtime.mjs --resolve: newest by semver, no drafts, no prereleases. */
+function newestCodeRelease(rows) {
+  return rows.filter((row) => !row.isDraft && !row.isPrerelease && semver(row.tagName))
+    .sort((a, b) => { const x = semver(a.tagName); const y = semver(b.tagName); return y[0] - x[0] || y[1] - x[1] || y[2] - x[2]; })[0] || null;
+}
+
+function assetNames(gh, repo, tag) {
+  return new Set((JSON.parse(gh(['release', 'view', tag, '--repo', repo, '--json', 'assets'])).assets || []).map((asset) => asset.name));
+}
+function download(gh, repo, tag, name, dir) {
+  gh(['release', 'download', tag, '--repo', repo, '--pattern', name, '--dir', dir, '--clobber']);
+  return fs.readFileSync(path.join(dir, name));
+}
+
+async function aggregateState({ gh, repo, tag, root, scratch }) {
+  if (!assetNames(gh, repo, tag).has(AGGREGATE_ASSET)) return { state: 'missing' };
+  try {
+    const aggregate = JSON.parse(download(gh, repo, tag, AGGREGATE_ASSET, scratch).toString('utf8'));
+    const { verifyPublicVerificationAggregate } = await import('./public-verification-aggregate.mjs');
+    verifyPublicVerificationAggregate(aggregate, crypto.createPublicKey(fs.readFileSync(path.join(root, SIGNING_PUBLIC_KEY_FILE), 'utf8')));
+    if (aggregate.identity?.tag !== tag) throw new Error(`aggregate describes ${aggregate.identity?.tag}, not ${tag}`);
+    return { state: 'verified' };
+  } catch (error) {
+    return { state: 'invalid', reason: error.message.slice(0, 200) };
+  }
+}
+
+function generationCoverage({ gh, repo, tag, scratch }) {
+  const names = assetNames(gh, repo, tag);
+  if (!names.has(COVERAGE_ASSET) || !names.has(COVERAGE_RECEIPT_ASSET)) return null;
+  const dir = fs.mkdtempSync(path.join(scratch, 'coverage-'));
+  const { degraded } = verifyCoverageSidecar({
+    sidecar: JSON.parse(download(gh, repo, tag, COVERAGE_RECEIPT_ASSET, dir).toString('utf8')),
+    coverageBytes: download(gh, repo, tag, COVERAGE_ASSET, dir),
+    generationTag: tag,
+    archiveSha256: tag.slice('corpus-sha256-'.length),
+  });
+  return degraded;
+}
+
+function corpusRunEvidence({ gh, repo, run, scratch }) {
+  if (run.status !== 'completed') return {};
+  const dir = fs.mkdtempSync(path.join(scratch, 'outcome-'));
+  try {
+    gh(['run', 'download', String(run.databaseId), '--repo', repo, '--name', `corpus-release-outcome-${run.databaseId}-${run.attempt ?? 1}`, '--dir', dir]);
+    return { outcomeRecord: JSON.parse(fs.readFileSync(path.join(dir, 'corpus-release-outcome.json'), 'utf8')) };
+  } catch {
+    // Runs that never reached corpus-terminal-outcome have no record; their job list still says what happened.
+    return { jobs: JSON.parse(gh(['run', 'view', String(run.databaseId), '--repo', repo, '--json', 'jobs'])).jobs || [] };
+  }
+}
+
+export async function gatherCorpusHealthInput({ repo, now, gh = defaultGh, root = ROOT, scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-watchdog-')) }) {
+  const at = now.getTime();
+  const recent = (iso) => (ms(iso) ?? 0) >= at - 3 * 24 * HOUR;
+  const dispatcherRuns = JSON.parse(gh(['run', 'list', '--repo', repo, '--workflow', 'corpus-nightly-dispatch.yml', '--limit', '30',
+    '--json', 'databaseId,attempt,event,status,conclusion,createdAt,updatedAt']))
+    .map((run) => ({ id: run.databaseId, attempt: run.attempt, event: run.event, status: run.status, conclusion: run.conclusion, createdAt: run.createdAt }));
+  const corpusRuns = JSON.parse(gh(['run', 'list', '--repo', repo, '--workflow', 'protected-release.yml', '--limit', '60',
+    '--json', 'databaseId,attempt,displayTitle,status,conclusion,createdAt,updatedAt']))
+    .filter((run) => CORPUS_RUN_TITLE.test(String(run.displayTitle || '')) && recent(run.createdAt))
+    .map((run) => ({ id: run.databaseId, title: run.displayTitle, status: run.status, conclusion: run.conclusion,
+      createdAt: run.createdAt, updatedAt: run.updatedAt, ...corpusRunEvidence({ gh, repo, run, scratch }) }));
+  const releases = JSON.parse(gh(['release', 'list', '--repo', repo, '--limit', '100', '--json', 'tagName,publishedAt,isDraft,isPrerelease']));
+  const corpusReleases = releases.filter((row) => !row.isDraft && isCorpusReleaseTag(row.tagName))
+    .map((row) => ({ tag: row.tagName, publishedAt: row.publishedAt }))
+    .sort((a, b) => (ms(b.publishedAt) ?? 0) - (ms(a.publishedAt) ?? 0));
+  const newestCode = newestCodeRelease(releases);
+  const codeRelease = newestCode && { tag: newestCode.tagName, publishedAt: newestCode.publishedAt,
+    aggregate: await aggregateState({ gh, repo, tag: newestCode.tagName, root, scratch }) };
+
+  // Deferral: newest generation's verified coverage, then older ones only while it can still matter.
+  let deferral = { observable: false, reason: 'no corpus release is published' };
+  if (corpusReleases.length) {
+    const generations = [];
+    for (const release of corpusReleases.slice(0, 15)) {
+      const degraded = generationCoverage({ gh, repo, tag: release.tag, scratch });
+      generations.push({ ...release, degraded });
+      const pending = generations[0].degraded && [...generations[0].degraded.carried, ...generations[0].degraded.missing];
+      if (!degraded || !pending?.length || (ms(release.publishedAt) ?? 0) < at - DEFERRAL_LIMIT_MS - 24 * HOUR) break;
+    }
+    deferral = generations[0].degraded
+      ? { observable: true, newestTag: generations[0].tag, degraded: generations[0].degraded, stores: deferralSince(generations) }
+      // Generations published before ADR-0091 D6.2 carry no CORPUS-COVERAGE.json / coverage-receipt.json,
+      // so which stores were carried, and since when, is simply not recorded anywhere a reader can verify.
+      : { observable: false, reason: `${generations[0].tag} predates the D6.2 coverage sidecar (${COVERAGE_ASSET} + ${COVERAGE_RECEIPT_ASSET})` };
+  }
+  return { corpusReleases, corpusRuns, dispatcherRuns, codeRelease, deferral };
+}
+
+export function renderReport(result, now) {
+  const lines = [`corpus-watchdog ${result.verdict} at ${now.toISOString()}`];
+  for (const f of result.findings) lines.push(`  [${f.level}] ${f.check}: ${f.detail}`);
+  return `${lines.join('\n')}\n`;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const opt = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+  const repo = opt('--repo') || process.env.GITHUB_REPOSITORY || 'stuinfla/ruvnet-brain';
+  const now = opt('--now') ? new Date(opt('--now')) : new Date();
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repo) || !Number.isFinite(now.getTime())) {
+    process.stderr.write('usage: corpus-watchdog.mjs [--repo owner/name] [--json] [--now ISO]\n');
+    return 2;
+  }
+  let result;
+  try {
+    result = judgeCorpusHealth(await gatherCorpusHealthInput({ repo, now }), now);
+  } catch (error) {
+    // Could not observe = could not prove health. Absence of evidence is failure.
+    process.stderr.write(`corpus-watchdog RED: evidence could not be gathered: ${error.message}\n`);
+    return 1;
+  }
+  process.stdout.write(argv.includes('--json') ? `${JSON.stringify(result, null, 2)}\n` : renderReport(result, now));
+  return result.verdict === RED ? 1 : 0;
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  main().then((code) => { process.exitCode = code; });
+}

package/scripts/derive-passage-content-map.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Derive data/retrieval-passage-content-digests.json from a corpus archive built with ordinal passage
+// ids. See scripts/retrieval-passage-identity.mjs for why the map exists.
+//
+//   node scripts/derive-passage-content-map.mjs --zip <old-format ruvnet-brain.zip> \
+//        --source-tag v4.3.36 [--fixture data/retrieval-query-evidence.json] [--out <file>]
+//
+// For every expected passage the frozen fixture pins (primary + alternatives), find the ONE row in the
+// archive's store whose path matches and whose digest equals the pin, and record that row's id-less
+// content digest. A pin that is not found exactly once is listed as `unresolved` (never guessed): it
+// keeps exact-digest matching only. The output is deterministic, so re-running proves the committed map.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { digest } from './coverage-integrity.mjs';
+import { CONTENT_MAP_FILE, CONTENT_MAP_KIND, passageContentDigest } from './retrieval-passage-identity.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const sha256File = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+/** Every pin in the fixture: [{ store, path, pinned }]. */
+export function fixturePins(fixture) {
+  const pins = [];
+  for (const [store, row] of Object.entries(fixture.queries || {})) {
+    const sources = [{ path: row.expected.path, passageSha256: row.expected.passageSha256 }, ...(row.expected.alternatives || [])];
+    for (const source of sources) pins.push({ store, path: source.path, pinned: source.passageSha256 });
+  }
+  return pins;
+}
+
+export function deriveContentMap({ fixture, fixtureSha256, readRows, sourceTag, archiveSha256 }) {
+  const entries = {};
+  const unresolved = [];
+  for (const { store, path: expectedPath, pinned } of fixturePins(fixture)) {
+    const rows = readRows(store);
+    const found = (rows || []).filter((row) => row.path === expectedPath && digest(row) === pinned);
+    if (found.length === 1) entries[pinned] = passageContentDigest(found[0]);
+    else unresolved.push({ store, path: expectedPath, pinned, reason: rows ? `${found.length} matching rows` : 'store absent from archive' });
+  }
+  const sorted = Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+  return { schemaVersion: 1, kind: CONTENT_MAP_KIND, fixtureSha256,
+    derivedFrom: { tag: sourceTag, archiveSha256 },
+    entries: sorted,
+    unresolved: unresolved.sort((a, b) => a.store.localeCompare(b.store) || a.path.localeCompare(b.path)) };
+}
+
+function zipRows(zipFile, store) {
+  const result = spawnSync('unzip', ['-p', zipFile, `${store}.passages.jsonl`], { maxBuffer: 1 << 30 });
+  if (result.status !== 0) return null;
+  // Split on \n only: rows may contain U+2028/U+2029, which are not JSONL separators.
+  return result.stdout.toString('utf8').split('\n').filter((line) => line.trim()).map((line) => JSON.parse(line));
+}
+
+function main(argv) {
+  const arg = (name, fallback = null) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : fallback; };
+  const zip = arg('--zip');
+  const sourceTag = arg('--source-tag');
+  if (!zip || !sourceTag) { console.error('usage: derive-passage-content-map.mjs --zip <archive> --source-tag <tag> [--fixture f] [--out f]'); process.exit(2); }
+  const fixtureFile = path.resolve(arg('--fixture', path.join(ROOT, 'data', 'retrieval-query-evidence.json')));
+  const out = path.resolve(arg('--out', CONTENT_MAP_FILE));
+  const cache = new Map();
+  const readRows = (store) => { if (!cache.has(store)) cache.set(store, zipRows(zip, store)); return cache.get(store); };
+  const map = deriveContentMap({ fixture: JSON.parse(fs.readFileSync(fixtureFile, 'utf8')), fixtureSha256: sha256File(fixtureFile),
+    readRows, sourceTag, archiveSha256: sha256File(zip) });
+  fs.writeFileSync(out, `${JSON.stringify(map, null, 2)}\n`);
+  console.log(JSON.stringify({ out, resolved: Object.keys(map.entries).length, unresolved: map.unresolved.length }));
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));

package/scripts/fixture-denominator.mjs

@@ -0,0 +1,72 @@
+// scripts/fixture-denominator.mjs — ADR-0091 D6.4 (and the one retirement function D7.7 requires).
+//
+// The retrieval fixture is FROZEN (182 human questions, one per repository, digest-bound). Live
+// coverage is not: 194+ eligible repositories and growing. The release canary used to demand that
+// the two sets be EQUAL, which a living corpus can never satisfy. The reconciled decision:
+//
+//   available  = eligible repository rows that ship a store (CURRENT, or STALE with a verified carry)
+//   retired    = fixture repositories with NO row at all in a complete coverage observation (D7.2)
+//   questioned = fixture ∩ available            -- every one is asked its frozen question
+//   blocking   = fixture − available − retired  -- the release refuses (e.g. MISSING, INELIGIBLE)
+//   unfixturedEligible = available − fixture    -- RECORDED, never blocking; the fixture stays frozen
+//
+// Retirement only ever REMOVES a question from the denominator; it never adds a passing answer. The
+// signal is "absent from a sealed, complete enumeration" -- it cannot tell deleted from privatized
+// from renamed, which is acceptable for exactly that reason (ADR-0091 D7.2).
+
+import { eligibleRepositoryStanding } from '../plugin/scripts/coverage-integrity.mjs';
+
+const lower = (value) => String(value || '').toLowerCase();
+// localeCompare, exactly as scripts/retrieval-canary.mjs orders and set-checks these lists. Default
+// code-unit sort disagrees on real store names ('chatgpt-…' vs 'chatgpt_…'), which the canary's
+// checkedSet rejects as 'eligible denominator set is invalid'.
+const ordered = (values) => [...new Set(values)].sort((a, b) => a.localeCompare(b));
+
+/** True only for a repository enumeration the coverage itself proves complete and terminal. */
+export function repositoryEnumerationComplete(coverage) {
+  const repositories = (coverage?.rows || []).filter((row) => row?.kind === 'repository');
+  const enumeration = coverage?.enumerationReceipt;
+  return enumeration?.terminal === true && enumeration?.duplicateKeys === 0
+    && enumeration?.repositories?.expected === repositories.length;
+}
+
+/** D7.2: fixture stores with no repository row at all, under a complete enumeration; else none. */
+export function retiredFixtureStores({ coverage, fixtureStores }) {
+  if (!repositoryEnumerationComplete(coverage)) return [];
+  const present = new Set();
+  for (const row of (coverage.rows || []).filter((entry) => entry?.kind === 'repository')) {
+    present.add(lower(row.name));
+    if (row.artifact?.store) present.add(lower(row.artifact.store));
+  }
+  return ordered(fixtureStores.map(lower).filter((store) => !present.has(store)));
+}
+
+export function fixtureDenominator({ coverage, fixtureStores }) {
+  const fixture = ordered((fixtureStores || []).map(lower));
+  if (!fixture.length || fixture.some((store) => !store)) throw new Error('fixture store set is empty or malformed');
+  const eligible = (coverage?.rows || []).filter((row) => row?.kind === 'repository' && row.disposition === 'eligible');
+  const available = new Map();
+  for (const row of eligible) {
+    if (eligibleRepositoryStanding(row) !== 'shipped') continue;
+    const store = lower(row.artifact?.store);
+    if (!store) throw new Error(`eligible repository row ${row.key} names no store`);
+    if (available.has(store)) throw new Error(`eligible repository store ${store} is duplicated`);
+    available.set(store, row);
+  }
+  const retired = new Set(retiredFixtureStores({ coverage, fixtureStores: fixture }));
+  const questioned = fixture.filter((store) => available.has(store));
+  const blocking = fixture.filter((store) => !available.has(store) && !retired.has(store)).map((store) => {
+    const row = (coverage?.rows || []).find((entry) => entry?.kind === 'repository'
+      && (lower(entry.artifact?.store) === store || lower(entry.name) === store));
+    return { store, status: row?.status ?? null, disposition: row?.disposition ?? null };
+  });
+  const fixtureSet = new Set(fixture);
+  return {
+    fixture,
+    questioned,
+    questionedRows: questioned.map((store) => available.get(store)),
+    retired: [...retired],
+    blocking,
+    unfixturedEligible: ordered([...available.keys()].filter((store) => !fixtureSet.has(store))),
+  };
+}