ruvnet-brain 4.3.34 → 4.3.36

package/scripts/code-release-corpus.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// scripts/code-release-corpus.mjs — ADR-0091 D6: a code release is built from the newest compatible
+// corpus generation, through one of TWO assembly paths chosen by where the seed came from.
+//
+//   seed origin                      path               what runs
+//   -------------------------------  -----------------  ---------------------------------------------
+//   published-generation             single-pass        observe-baseline, ONE build-bundle with the
+//   (corpus-sha256-<digest>, with                       generation's sealed coverage. The generation's
+//   its D6.2 coverage sidecar)                          bytes are NEVER mutated: no capability-only
+//                                                       refresh, no index repair. Proven afterwards.
+//   committed-bootstrap (v4.3.26,    legacy-two-pass    exactly the pre-D6 ci.yml sequence: capability-
+//   pre-ADR-0091 Step 4)                                only refresh + index repair, observe-baseline,
+//                                                       build / release-projection / build.
+//
+// This is a genuine dual path, not one path with a flag to retire: the bootstrap remains the recovery
+// seed (ADR-0091 D6.1), and it predates every sealed-input contract the single-pass assembly checks.
+// Running refreshCapabilityOnlyStore on a sealed generation would rewrite one store and prune another
+// AFTER the generation's coverage measured them, so the coverage would describe bytes the release
+// does not ship. The path choice lives in ONE function (assemblyPathFor) so a test can prove neither
+// collapses into the other.
+//
+// It also owns the D6.6 publish-time guard (assertNoNewerCorpusGeneration), because it is the same
+// resolver question asked a second time.
+//
+// Usage (ci.yml release-qe, after downloading and extracting the resolved seed):
+//   node scripts/code-release-corpus.mjs assemble --descriptor <release-evidence/corpus-seed.json>
+//        --seed-bundle <seed zip> --assets <extracted seed dir> --evidence-dir <release-evidence>
+//        [--coverage <CORPUS-COVERAGE.json> --coverage-receipt <coverage-receipt.json>]   (single-pass only)
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
+import { resolveNextCorpusSeed } from './corpus-next-seed.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CORPUS_TAG = /^corpus-sha256-([0-9a-f]{64})$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+export const SINGLE_PASS = 'single-pass';
+export const LEGACY_TWO_PASS = 'legacy-two-pass';
+// The seed reader modules the legacy capability-only refresh embeds with -- the exact pins the pre-D6
+// ci.yml step installed (npm package @ruvector/rvf 0.3.4: ruvector/npm/packages/rvf/package.json).
+const LEGACY_READER_PACKAGES = ['@xenova/transformers@2.17.2', '@ruvector/rvf@0.3.4'];
+// Every file of a store family build-bundle copies from the corpus (build-bundle.mjs step 3).
+const STORE_SUFFIXES = ['.big.rvf', '.big.rvf.idmap.json', '.big.rvf.embed.json', '.passages.jsonl', '.meta.json',
+  '.symbols.json', '.sources.json'];
+
+function fail(message) {
+  throw new Error(`[code-release-corpus] ${message}`);
+}
+
+function sha256File(file) {
+  const hash = crypto.createHash('sha256');
+  const fd = fs.openSync(file, 'r');
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  try {
+    let bytes;
+    while ((bytes = fs.readSync(fd, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, bytes));
+  } finally { fs.closeSync(fd); }
+  return hash.digest('hex');
+}
+
+/** The ONE place the path is chosen. Anything that is neither shape is refused, never defaulted. */
+export function assemblyPathFor(descriptor) {
+  if (descriptor?.origin === 'published-generation') {
+    const match = CORPUS_TAG.exec(String(descriptor.tag || ''));
+    if (!match || match[1] !== descriptor.sha256) fail(`generation seed tag ${descriptor.tag} does not name its own digest`);
+    if (!descriptor.coverage || !HEX64.test(String(descriptor.coverage.sha256 || ''))) {
+      fail(`generation seed ${descriptor.tag} was resolved without its coverage sidecar; resolve with --require-coverage`);
+    }
+    return SINGLE_PASS;
+  }
+  if (descriptor?.origin === 'committed-bootstrap') {
+    if (CORPUS_TAG.test(String(descriptor.tag || ''))) fail('a committed bootstrap seed must be the pinned pre-ADR-0091 tag, not a generation tag');
+    return LEGACY_TWO_PASS;
+  }
+  fail(`resolved seed has no recognised origin (${JSON.stringify(descriptor?.origin ?? null)}); `
+    + 'it must come from scripts/corpus-next-seed.mjs');
+}
+
+/** Digest of every regular file under `dir` -- the "was the sealed generation touched?" proof. */
+export function treeDigest(dir) {
+  const rows = [];
+  const walk = (current, prefix) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const file = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(file, relative);
+      else if (entry.isFile()) rows.push(`${relative}\0${sha256File(file)}`);
+    }
+  };
+  walk(path.resolve(dir), '');
+  rows.sort();
+  return { files: rows.length, sha256: crypto.createHash('sha256').update(rows.join('\n')).digest('hex') };
+}
+
+/**
+ * ADR-0091 V6a: the assembled archive ships the generation's store bytes, unchanged. The store set
+ * must equal the generation's ledger, and every store-family file in the assembly must be
+ * byte-identical to the generation's copy.
+ */
+export function assertStoresUnmutated({ seedDir, bundleDir }) {
+  const readLedger = (dir) => JSON.parse(fs.readFileSync(path.join(dir, 'RVF-GENERATIONS.json'), 'utf8'));
+  const seedStores = Object.keys(readLedger(seedDir).stores || {}).map((name) => name.toLowerCase()).sort();
+  const bundleStores = Object.keys(readLedger(bundleDir).stores || {}).sort();
+  if (JSON.stringify(bundleStores.map((name) => name.toLowerCase())) !== JSON.stringify(seedStores)) {
+    fail(`assembled store set differs from the generation's (${bundleStores.length} vs ${seedStores.length})`);
+  }
+  let compared = 0;
+  const changed = [];
+  for (const store of bundleStores) {
+    for (const suffix of STORE_SUFFIXES) {
+      const shipped = path.join(bundleDir, `${store}${suffix}`);
+      if (!fs.existsSync(shipped)) continue;
+      const sealed = path.join(seedDir, `${store}${suffix}`);
+      if (!fs.existsSync(sealed) || sha256File(sealed) !== sha256File(shipped)) changed.push(`${store}${suffix}`);
+      compared += 1;
+    }
+  }
+  if (changed.length) fail(`assembly changed ${changed.length} store file(s) the generation sealed: ${changed.slice(0, 5).join(', ')}`);
+  return { stores: bundleStores.length, files: compared };
+}
+
+const defaultRun = (command, args, options = {}) => spawnSync(command, args, { stdio: 'inherit', ...options });
+
+function checkedRun(run, label, command, args, options) {
+  const result = run(command, args, options) || {};
+  if (result.error || result.status !== 0) {
+    fail(`${label} failed (${result.error?.message || `exit ${result.status}`})`);
+  }
+  return result;
+}
+
+/**
+ * Assemble the release bundle into <root>/dist from the resolved seed. `run` is the process seam: the
+ * tests record it to prove which commands each path runs, and in which order.
+ */
+export function assembleCodeReleaseCorpus({
+  root = ROOT, descriptor, seedBundle, assetsDir, evidenceDir, coverageFile = null, coverageReceiptFile = null,
+  run = defaultRun, env = process.env,
+} = {}) {
+  const mode = assemblyPathFor(descriptor);
+  const node = process.execPath;
+  const script = (name) => path.join(root, 'scripts', name);
+  const version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+  const assets = path.resolve(assetsDir || '');
+  const evidence = path.resolve(evidenceDir || '');
+  const baselineReceipt = path.join(evidence, 'baseline-observation-receipt.json');
+  const observeBaseline = () => {
+    checkedRun(run, 'observe-baseline', node, [script('public-verification-inputs.mjs'), 'observe-baseline',
+      '--baseline-bundle', seedBundle, '--expected-tag', descriptor.tag, '--expected-sha256', descriptor.sha256,
+      '--expected-bytes', String(descriptor.bytes), '--out', baselineReceipt], { cwd: root, env });
+    return sha256File(baselineReceipt);
+  };
+
+  if (mode === LEGACY_TWO_PASS) {
+    // The pre-D6 ci.yml sequence, unchanged. The public ruOS input is capabilities-only and the
+    // bootstrap predates that policy, so its RVF is rebuilt from the curated summary; --repair also
+    // re-seals stale ledger hashes after index persistence (the v4.2.1 seed exposed three roots whose
+    // HNSW bytes advanced after their ledger rows were written).
+    checkedRun(run, 'install seed reader dependencies', 'npm', ['install', '--prefix', assets, '--no-save',
+      '--package-lock=false', '--ignore-scripts', ...LEGACY_READER_PACKAGES], { cwd: root, env });
+    const embedEnv = { ...env, XENOVA_PATH: path.join(assets, 'node_modules', '@xenova', 'transformers'),
+      RVF_MODULE_PATH: path.join(assets, 'node_modules') };
+    checkedRun(run, 'capability-only refresh', node, [script('refresh-capability-only-store.mjs'), '--assets', assets],
+      { cwd: root, env: embedEnv });
+    checkedRun(run, 'index repair', node, [script('rvf-index-audit.mjs'), '--dir', assets, '--repair'], { cwd: root, env: embedEnv });
+    const baselineSha256 = observeBaseline();
+    const build = ['--version', `v${version}`, '--assets', assets, '--legacy-seed-projection'];
+    checkedRun(run, 'legacy build pass 1', node, [script('build-bundle.mjs'), ...build], { cwd: root, env });
+    const projection = path.join(path.dirname(evidence), 'release-projection');
+    checkedRun(run, 'release projection', node, [script('release-projection.mjs'), '--corpus', 'data/source-coverage.json',
+      '--assets', 'dist/ruvnet-brain', '--out', projection, '--version', version,
+      '--source-snapshot', env.GITHUB_SHA || '', '--baseline-receipt-sha256', baselineSha256,
+      '--seed-tag', descriptor.tag, '--seed-sha256', descriptor.sha256, '--seed-bytes', String(descriptor.bytes)], { cwd: root, env });
+    checkedRun(run, 'legacy build pass 2', node, [script('build-bundle.mjs'), ...build,
+      '--coverage', path.join(projection, 'COVERAGE.json'), '--projection', projection], { cwd: root, env });
+    return { mode };
+  }
+
+  // SINGLE-PASS. The coverage file must be the one the resolver bound to this generation.
+  const coverageBytes = fs.readFileSync(path.resolve(coverageFile || ''));
+  const verified = verifyCoverageSidecar({ sidecar: JSON.parse(fs.readFileSync(path.resolve(coverageReceiptFile || ''), 'utf8')),
+    coverageBytes, generationTag: descriptor.tag, archiveSha256: descriptor.sha256, archiveBytes: descriptor.bytes });
+  if (crypto.createHash('sha256').update(coverageBytes).digest('hex') !== descriptor.coverage.sha256) {
+    fail('the downloaded coverage is not the coverage the resolver sealed into the descriptor');
+  }
+  if (verified.degraded.carried.length || verified.degraded.missing.length) {
+    fail(`generation ${descriptor.tag} is degraded (${verified.degraded.carried.length} carried, `
+      + `${verified.degraded.missing.length} missing); a code release does not ship one (ADR-0091 D10)`);
+  }
+  const before = treeDigest(assets);
+  // build-bundle reads the sealed coverage from the ONE canonical path (<root>/data/source-coverage.json),
+  // exactly as prepareCorpusCandidate does. The committed file is restored afterwards so no later
+  // release-QE step reads the generation's coverage believing it is the checkout's.
+  const canonical = path.join(root, 'data', 'source-coverage.json');
+  const committed = fs.existsSync(canonical) ? fs.readFileSync(canonical) : null;
+  try {
+    fs.writeFileSync(canonical, coverageBytes);
+    const baselineSha256 = observeBaseline();
+    checkedRun(run, 'single-pass build', node, [script('build-bundle.mjs'), '--version', `v${version}`, '--assets', assets,
+      '--coverage', canonical, '--seed-tag', descriptor.tag, '--seed-sha256', descriptor.sha256,
+      '--seed-bytes', String(descriptor.bytes), '--baseline-receipt-sha256', baselineSha256], { cwd: root, env });
+  } finally {
+    if (committed === null) fs.rmSync(canonical, { force: true });
+    else fs.writeFileSync(canonical, committed);
+  }
+  const after = treeDigest(assets);
+  if (after.sha256 !== before.sha256) fail(`the sealed generation directory was modified during assembly (${before.files} -> ${after.files} files)`);
+  const unmutated = assertStoresUnmutated({ seedDir: assets, bundleDir: path.join(root, 'dist', 'ruvnet-brain') });
+  return { mode, seedTree: before, unmutated };
+}
+
+/**
+ * ADR-0091 D6.6. `sealed` is the descriptor release QE sealed into the payload; `resolution` is a fresh
+ * resolveNextCorpusSeed({ requireCoverage: true }) answer. Refuses on any difference, and on any
+ * resolution that could not prove there is nothing newer (a failed list, view or small download).
+ */
+export function checkNoNewerCorpusGeneration({ sealed, resolution }) {
+  if (!sealed?.origin || !sealed?.tag || !HEX64.test(String(sealed.sha256 || ''))) {
+    fail('the sealed corpus seed descriptor carries no resolver origin/tag/sha256; it did not come from corpus-next-seed.mjs');
+  }
+  const indeterminate = (resolution?.rejected || []).filter((row) => row.indeterminate);
+  if (indeterminate.length) {
+    fail(`cannot prove no newer corpus generation was published (${indeterminate.map((row) => `${row.tag || '(list)'}: ${row.reason}`).join('; ')})`);
+  }
+  const now = resolution?.seed;
+  if (now?.tag !== sealed.tag || now?.sha256 !== sealed.sha256) {
+    fail(`corpus generation ${now?.tag} published after this release was QE'd from ${sealed.tag}; re-run release QE`);
+  }
+  return { origin: sealed.origin, tag: sealed.tag };
+}
+
+export async function assertNoNewerCorpusGeneration({ sealedFile, repo, runtimeRoot = ROOT, run = undefined,
+  resolve = resolveNextCorpusSeed } = {}) {
+  const sealed = JSON.parse(fs.readFileSync(sealedFile, 'utf8'));
+  const resolution = await resolve({ repo, root: runtimeRoot, runtimeRoot, requireCoverage: true, ...(run ? { run } : {}) });
+  return checkNoNewerCorpusGeneration({ sealed, resolution });
+}
+
+const arg = (argv, name) => {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+};
+
+export function main(argv = process.argv.slice(2)) {
+  if (argv[0] !== 'assemble') {
+    process.stderr.write('usage: code-release-corpus.mjs assemble --descriptor <f> --seed-bundle <f> --assets <d> --evidence-dir <d> [--coverage <f> --coverage-receipt <f>]\n');
+    return 2;
+  }
+  const descriptor = JSON.parse(fs.readFileSync(arg(argv, '--descriptor'), 'utf8'));
+  const result = assembleCodeReleaseCorpus({
+    descriptor,
+    seedBundle: arg(argv, '--seed-bundle'),
+    assetsDir: arg(argv, '--assets'),
+    evidenceDir: arg(argv, '--evidence-dir'),
+    coverageFile: arg(argv, '--coverage'),
+    coverageReceiptFile: arg(argv, '--coverage-receipt'),
+  });
+  process.stdout.write(`${JSON.stringify({ ok: true, seed: descriptor.tag, ...result })}\n`);
+  return 0;
+}
+
+function isMain() {
+  try {
+    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  try { process.exitCode = main(); } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/scripts/corpus-candidate.mjs

@@ -124,7 +124,7 @@ function normalizeBootstrapIdentity(bootstrapIdentity) {
 // from bundleFile, or is one of the three inputs that are not archive-derived (builderSourceSha,
 // bootstrapIdentity, createdAt) — verification supplies those from the receipt being checked, so a
 // receipt can never claim archive contents that were not really shipped.
-async function deriveCorpusCandidate({ bundleFile, builderSourceSha, bootstrapIdentity, createdAt, accuracyReportFile, recallReportFile }) {
+async function deriveCorpusCandidate({ bundleFile, builderSourceSha, bootstrapIdentity, createdAt, accuracyReportFile, recallReportFile, coverageFile = null }) {
   const bundle = path.resolve(bundleFile || '');
   if (!fs.existsSync(bundle) || !fs.statSync(bundle).isFile()) fail(`bundle missing (${bundle || 'no path supplied'})`);
   if (!HEX_SOURCE.test(builderSourceSha || '')) fail('builderSourceSha must be a 40-64 hex source identity');
@@ -145,10 +145,16 @@ async function deriveCorpusCandidate({ bundleFile, builderSourceSha, bootstrapId
   // a DECLARED REDUCTION in release requirements, not a demonstration that C3 passed — so the C3
   // report is still required to exist and still bound to these exact archive bytes, and is published
   // alongside rather than quietly dropped.
+  // ADR-0091 D7.3: a report that claims retired questions is only accepted against this candidate's
+  // sealed coverage (the archive carries none, and the schema-3 receipt binds none), recomputed here
+  // from those bytes. With no coverage supplied, any claimed retirement is rejected.
+  const fixture = loadFixture();
   const recall = readRecallReport({
     reportFile: recallReportFile || `${bundle}.recall.json`,
     archive,
-    expectedFixtureSha256: loadFixture().fixtureSha256,
+    expectedFixtureSha256: fixture.fixtureSha256,
+    coverageBytes: coverageFile ? fs.readFileSync(path.resolve(coverageFile)) : null,
+    fixtureStores: fixture.questions.map((question) => question.store),
   });
   const accuracyDiagnostic = readDiagnosticAccuracyReport({
     reportFile: accuracyReportFile || `${bundle}.accuracy.json`,
@@ -418,6 +424,7 @@ function currentGitSha() {
 
 export async function createCorpusReceipt({
   bundleFile, builderSourceSha, bootstrapIdentity = null, receiptFile, createdAt, accuracyReportFile = null, recallReportFile = null,
+  coverageFile = null,
 } = {}) {
   const resolvedReceiptFile = path.resolve(receiptFile || 'dist/corpus-receipt.json');
   const receipt = await deriveCorpusCandidate({
@@ -427,6 +434,7 @@ export async function createCorpusReceipt({
     createdAt: createdAt || new Date().toISOString(),
     accuracyReportFile,
     recallReportFile,
+    coverageFile,
   });
   fs.mkdirSync(path.dirname(resolvedReceiptFile), { recursive: true });
   fs.writeFileSync(resolvedReceiptFile, `${JSON.stringify(receipt, null, 2)}\n`);
@@ -435,6 +443,7 @@ export async function createCorpusReceipt({
 
 export async function verifyCorpusReceipt({
   bundleFile, receiptFile, expectedBuilderSha, expectedArchiveSha256, expectedReceiptSha256, accuracyReportFile = null, recallReportFile = null,
+  coverageFile = null,
 } = {}) {
   const resolvedReceiptFile = path.resolve(receiptFile || '');
   const resolvedBundleFile = path.resolve(bundleFile || '');
@@ -465,6 +474,7 @@ export async function verifyCorpusReceipt({
     createdAt: receipt.createdAt,
     accuracyReportFile,
     recallReportFile,
+    coverageFile,
   });
   if (canonicalJson(derived) !== canonicalJson(receipt)) fail('receipt does not match the exact corpus archive contents');
   return receipt;
@@ -474,7 +484,9 @@ export async function verifyCorpusReceipt({
 // (corpus-sha256-<digest>) and its accompanying schema-2 candidate receipt. This never compares
 // the external tag against the archive's own internal ARCHIVE-MANIFEST releaseTag/version — those
 // are two independent identity domains and conflating them was the historical bug this fixes.
-export async function verifySeedBaseline({ seedDescriptor, bundleFile, receiptFile, accuracyReportFile = null, recallReportFile = null } = {}) {
+export async function verifySeedBaseline({
+  seedDescriptor, bundleFile, receiptFile, accuracyReportFile = null, recallReportFile = null, coverageFile = null,
+} = {}) {
   if (!seedDescriptor || typeof seedDescriptor !== 'object') fail('seed descriptor is required');
   const { tag, sha256, bytes, sourceCommit = null, allowPinnedTag = false } = seedDescriptor;
   const expectedSha256 = String(sha256 || '').toLowerCase();
@@ -498,6 +510,7 @@ export async function verifySeedBaseline({ seedDescriptor, bundleFile, receiptFi
     receiptFile,
     accuracyReportFile,
     recallReportFile,
+    coverageFile,
     expectedArchiveSha256: expectedSha256,
     ...(sourceCommit ? { expectedBuilderSha: sourceCommit } : {}),
   });
@@ -515,6 +528,7 @@ async function main() {
   const receiptFile = arg('--receipt', arg('--out', 'dist/corpus-receipt.json'));
   const accuracyReportFile = arg('--accuracy-report');
   const recallReportFile = arg('--recall-report');
+  const coverageFile = arg('--coverage');
   if (mode === 'create') {
     const bootstrapTag = arg('--bootstrap-tag');
     const bootstrapSha256 = arg('--bootstrap-sha256');
@@ -526,6 +540,7 @@ async function main() {
       receiptFile,
       accuracyReportFile,
       recallReportFile,
+      coverageFile,
     });
     console.log(JSON.stringify({
       ok: true, mode, archive: receipt.archive, stores: receipt.storeCount, accuracyReport: receipt.accuracyReport, recall: receipt.recallSummary,
@@ -536,6 +551,7 @@ async function main() {
       receiptFile,
       accuracyReportFile,
       recallReportFile,
+      coverageFile,
       expectedBuilderSha: arg('--expected-builder-sha'),
       expectedArchiveSha256: arg('--expected-archive-sha256'),
       expectedReceiptSha256: arg('--expected-receipt-sha256'),

package/scripts/corpus-coverage-sidecar.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// scripts/corpus-coverage-sidecar.mjs — ADR-0091 D6.2: a corpus generation publishes its own sealed
+// coverage, as two small release assets beside the archive, WITHOUT bumping the schema-3 receipt.
+//
+// Why a sidecar and not a receipt field: three readers require receipt schema 3 exactly
+// (corpus-next-seed.mjs, release.mjs, corpus-candidate.mjs), and ADR-0091 D3 runs OLDER readers on the
+// nightly, so a schema bump breaks the nightly in one direction or the other. New readers use the
+// sidecar; old readers never look at it.
+//
+// Why it is needed at all (found while implementing D5): a corpus archive carries NO coverage file,
+// and the receipt binds none, so nothing downstream of preparation could tell a degraded generation
+// (carried / missing stores) from a fully current one. The coverage lived only in a 14-day workflow
+// artifact. D6's code-release path needs the generation's sealed coverage to assemble single-pass,
+// and D10's publisher-side "no degraded generation before the soak" check needs it to exist at all.
+//
+//   CORPUS-COVERAGE.json  -- the sealed ruvnet-brain-corpus-coverage ledger, exact bytes.
+//   coverage-receipt.json -- { generationTag, archiveSha256, archiveBytes, coverageSha256, ... }.
+//
+// A reader NEVER trusts the sidecar's own `degraded` summary: verifyCoverageSidecar recomputes it
+// from the coverage bytes the sidecar binds.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { eligibleRepositoryStanding, validateCoverageLedger } from '../plugin/scripts/coverage-integrity.mjs';
+
+export const COVERAGE_ASSET = 'CORPUS-COVERAGE.json';
+export const COVERAGE_RECEIPT_ASSET = 'coverage-receipt.json';
+export const COVERAGE_RECEIPT_KIND = 'ruvnet-brain-corpus-coverage-receipt';
+const CORPUS_TAG = /^corpus-sha256-([0-9a-f]{64})$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+
+function fail(message) {
+  throw new Error(`[corpus-coverage-sidecar] ${message}`);
+}
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const lower = (value) => String(value || '').toLowerCase();
+
+function parseCoverage(bytes) {
+  let coverage;
+  try { coverage = JSON.parse(Buffer.from(bytes).toString('utf8')); }
+  catch (error) { fail(`coverage is unreadable (${error.message})`); }
+  const checked = validateCoverageLedger(coverage);
+  if (coverage?.kind !== 'ruvnet-brain-corpus-coverage' || !checked.valid) {
+    fail(`coverage is not a valid sealed ruvnet-brain-corpus-coverage ledger (${checked.failures.join('; ') || coverage?.kind})`);
+  }
+  return coverage;
+}
+
+/**
+ * Every eligible row, classified by the SAME predicate the installed validator uses. Anything that is
+ * neither shipped nor a recorded absence is a blocker: such a coverage cannot describe a publishable
+ * generation at all.
+ */
+export function coverageStanding(coverage) {
+  const carried = [];
+  const missing = [];
+  const blockers = [];
+  const shipped = [];
+  for (const row of coverage.rows.filter((entry) => entry.disposition === 'eligible')) {
+    const store = lower(row.artifact?.store);
+    const standing = row.kind === 'repository' ? eligibleRepositoryStanding(row)
+      : row.status === 'CURRENT' && row.carry === undefined && row.failure === undefined ? 'shipped' : null;
+    if (standing === null) blockers.push(`${row.key}:${row.status}`);
+    else if (standing === 'absent') missing.push(store);
+    else {
+      if (row.carry) carried.push(store);
+      shipped.push({ row, store });
+    }
+  }
+  const sorted = (values) => [...new Set(values)].sort();
+  return { carried: sorted(carried), missing: sorted(missing), blockers, shipped };
+}
+
+/**
+ * The coverage describes THIS archive, not merely "a" corpus: every shipped eligible row's measured
+ * RVF digest (and, for a repository, its source generation) must be exactly what the schema-3
+ * receipt binds for that store, and the receipt's repository stores must be exactly the shipped
+ * repository rows -- no store the coverage does not account for, none it claims that is absent.
+ */
+export function bindCoverageToReceipt({ coverage, receipt }) {
+  const standing = coverageStanding(coverage);
+  if (standing.blockers.length) {
+    fail(`coverage has ${standing.blockers.length} eligible row(s) that are neither shipped nor a recorded absence `
+      + `(${standing.blockers.slice(0, 5).join(', ')})`);
+  }
+  const stores = new Map((Array.isArray(receipt?.stores) ? receipt.stores : []).map((store) => [lower(store?.name), store]));
+  for (const { row, store } of standing.shipped) {
+    const bound = stores.get(store);
+    if (!bound) fail(`coverage row ${row.key} names store ${store}, which the receipt does not bind`);
+    const rvf = (bound.files || []).find((file) => lower(file?.file) === `${store}.big.rvf`);
+    if (!rvf || lower(rvf.sha256) !== lower(row.artifact?.rvfSha256)) {
+      fail(`coverage row ${row.key} was measured against different ${store} RVF bytes than the receipt binds`);
+    }
+    if (row.kind === 'repository' && lower(bound.sourceCommit) !== lower(row.artifact?.sourceCommit)) {
+      fail(`coverage row ${row.key} records a different ${store} source generation than the receipt`);
+    }
+  }
+  const shippedRepositories = new Set(standing.shipped.filter(({ row }) => row.kind === 'repository').map(({ store }) => store));
+  const receiptRepositories = [...stores.values()].filter((store) => store?.kind === 'repository').map((store) => lower(store.name));
+  const unaccounted = receiptRepositories.filter((store) => !shippedRepositories.has(store)).sort();
+  if (unaccounted.length) fail(`receipt binds repository store(s) the coverage does not ship: ${unaccounted.join(', ')}`);
+  const shippedAbsent = standing.missing.filter((store) => stores.has(store));
+  if (shippedAbsent.length) fail(`coverage records store(s) as MISSING that the receipt ships: ${shippedAbsent.join(', ')}`);
+  return { carried: standing.carried, missing: standing.missing };
+}
+
+export function createCoverageReceipt({ generationTag, archiveSha256, archiveBytes, coverageBytes }) {
+  const digestMatch = CORPUS_TAG.exec(String(generationTag || ''));
+  if (!digestMatch || digestMatch[1] !== archiveSha256) fail('generation tag must be corpus-sha256-<the archive sha256>');
+  if (!Number.isSafeInteger(archiveBytes) || archiveBytes < 1) fail('archive byte length is malformed');
+  const coverage = parseCoverage(coverageBytes);
+  const { carried, missing } = coverageStanding(coverage);
+  return {
+    schemaVersion: 1,
+    kind: COVERAGE_RECEIPT_KIND,
+    generationTag,
+    archiveSha256,
+    archiveBytes,
+    coverageFile: COVERAGE_ASSET,
+    coverageSha256: sha256(coverageBytes),
+    coverageBytes: Buffer.byteLength(coverageBytes),
+    coverageGeneration: coverage.coverageGeneration,
+    degraded: { carried, missing },
+  };
+}
+
+/**
+ * The reader. Verifies the sidecar names THIS generation and THESE coverage bytes, re-validates the
+ * coverage ledger, and recomputes the degraded summary rather than trusting the sidecar's copy.
+ */
+export function verifyCoverageSidecar({ sidecar, coverageBytes, generationTag, archiveSha256, archiveBytes = null }) {
+  const keys = ['archiveBytes', 'archiveSha256', 'coverageBytes', 'coverageFile', 'coverageGeneration', 'coverageSha256',
+    'degraded', 'generationTag', 'kind', 'schemaVersion'];
+  if (!sidecar || typeof sidecar !== 'object' || JSON.stringify(Object.keys(sidecar).sort()) !== JSON.stringify(keys)
+    || sidecar.schemaVersion !== 1 || sidecar.kind !== COVERAGE_RECEIPT_KIND) fail('coverage receipt shape is not recognized');
+  if (sidecar.generationTag !== generationTag || !HEX64.test(String(archiveSha256 || '')) || sidecar.archiveSha256 !== archiveSha256
+    || (archiveBytes !== null && sidecar.archiveBytes !== archiveBytes)) {
+    fail(`coverage receipt names ${sidecar.generationTag}/${sidecar.archiveSha256}, not ${generationTag}/${archiveSha256}`);
+  }
+  if (sidecar.coverageFile !== COVERAGE_ASSET || sidecar.coverageSha256 !== sha256(coverageBytes)
+    || sidecar.coverageBytes !== Buffer.byteLength(coverageBytes)) {
+    fail('coverage bytes are not the ones the coverage receipt binds');
+  }
+  const coverage = parseCoverage(coverageBytes);
+  if (sidecar.coverageGeneration !== coverage.coverageGeneration) fail('coverage receipt names another coverage generation');
+  const { carried, missing, blockers } = coverageStanding(coverage);
+  if (blockers.length) fail(`coverage has eligible row(s) that are neither shipped nor a recorded absence (${blockers.slice(0, 5).join(', ')})`);
+  if (JSON.stringify(sidecar.degraded) !== JSON.stringify({ carried, missing })) {
+    fail('coverage receipt\'s degraded summary disagrees with the coverage it binds');
+  }
+  return { coverage, degraded: { carried, missing } };
+}
+
+/** Writes the two assets into `dir` (a fresh directory the publisher owns), returning their paths. */
+export function writeCoverageAssets({ dir, coverageFile, generationTag, archiveSha256, archiveBytes }) {
+  const coverageBytes = fs.readFileSync(coverageFile);
+  const receipt = createCoverageReceipt({ generationTag, archiveSha256, archiveBytes, coverageBytes });
+  fs.mkdirSync(dir, { recursive: true });
+  const coverageOut = path.join(dir, COVERAGE_ASSET);
+  const receiptOut = path.join(dir, COVERAGE_RECEIPT_ASSET);
+  fs.writeFileSync(coverageOut, coverageBytes, { flag: 'wx' });
+  fs.writeFileSync(receiptOut, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx' });
+  return { coverageFile: coverageOut, receiptFile: receiptOut, receipt };
+}
+
+const arg = (argv, name) => {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : undefined;
+};
+
+// CLI: `--verify --sidecar <f> --coverage <f> --tag <t> --archive-sha256 <h> [--archive-bytes <n>]`
+export function main(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (!argv.includes('--verify')) { stderr.write('usage: corpus-coverage-sidecar.mjs --verify ...\n'); return 2; }
+  try {
+    const bytes = arg(argv, '--archive-bytes');
+    const result = verifyCoverageSidecar({
+      sidecar: JSON.parse(fs.readFileSync(arg(argv, '--sidecar'), 'utf8')),
+      coverageBytes: fs.readFileSync(arg(argv, '--coverage')),
+      generationTag: arg(argv, '--tag'),
+      archiveSha256: arg(argv, '--archive-sha256'),
+      archiveBytes: bytes === undefined ? null : Number(bytes),
+    });
+    stdout.write(`${JSON.stringify({ ok: true, coverageGeneration: result.coverage.coverageGeneration, degraded: result.degraded })}\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}
+
+function isMain() {
+  try {
+    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) process.exitCode = main();

package/scripts/corpus-currency.mjs

@@ -0,0 +1,71 @@
+// scripts/corpus-currency.mjs — ADR-0091 D7.1: the honest content-currency block of manifest.json.
+//
+// There is no single honest "content as of" date for a corpus that mixes current and carried stores:
+// `builtUtc` is restamped to "now" every round (corpus-aggregates.mjs, refresh-capability-only-store.mjs)
+// and `manifest.generated` is the ASSEMBLY time. So the manifest reports what is actually known:
+//
+//   observedAt     when upstream heads were read (the sealed observation). Every CURRENT store equals
+//                  upstream as of that instant. null when nothing was observed (legacy/bootstrap path).
+//   generationTag  the corpus generation this archive was assembled FROM, when the build knows it (a
+//                  code release built from a published generation). null for a nightly candidate, whose
+//                  own tag is corpus-sha256-<this archive's sha256> and so cannot be written inside it.
+//   counts         eligible repository rows by status, plus fixture repositories RETIRED (no row at all
+//                  in a complete observation, scripts/fixture-denominator.mjs -- the one shared rule).
+//                  null when nothing was observed.
+//   oldestCarried  the carried (STALE + carry) store whose content is oldest. Its committedAt comes only
+//                  from carry.carriedCommittedAt; when any carried store's date is unknown the oldest
+//                  cannot be known, so an undated one is reported with committedAt null. Never estimated.
+//
+// Stated plainly, a surface reads it as "N of M repositories match upstream as of <observedAt>".
+
+import { retiredFixtureStores } from './fixture-denominator.mjs';
+
+export const CURRENCY_BASIS = Object.freeze({
+  SEALED: 'sealed-observation',
+  LEGACY: 'legacy-seed-projection-unobserved',
+  NONE: 'no-observation',
+});
+
+const isoOrNull = (value) => (typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : null);
+
+function oldestCarriedOf(rows) {
+  const carried = rows.filter((row) => row.status === 'STALE' && row.carry && typeof row.carry === 'object');
+  if (!carried.length) return null;
+  const byStore = (a, b) => String(a.artifact?.store).localeCompare(String(b.artifact?.store));
+  const undated = carried.filter((row) => isoOrNull(row.carry.carriedCommittedAt) === null).sort(byStore);
+  const pick = undated[0]
+    || [...carried].sort((a, b) => Date.parse(a.carry.carriedCommittedAt) - Date.parse(b.carry.carriedCommittedAt) || byStore(a, b))[0];
+  return {
+    store: pick.artifact?.store ?? null,
+    sourceCommit: pick.carry.carriedSourceCommit ?? null,
+    committedAt: isoOrNull(pick.carry.carriedCommittedAt),
+  };
+}
+
+/**
+ * `coverage`: the sealed ruvnet-brain-corpus-coverage this archive was bound to (already validated by
+ * the caller), or null. `basis` says why it is null. `fixtureStores`: the frozen fixture's stores, or
+ * null when the runtime has no fixture (then `retired` is null, not 0 -- unknown is not none).
+ */
+export function corpusCurrencyBlock({ coverage = null, basis, generationTag = null, fixtureStores = null }) {
+  if (!Object.values(CURRENCY_BASIS).includes(basis)) throw new Error(`unknown corpus currency basis ${basis}`);
+  if (basis !== CURRENCY_BASIS.SEALED || !coverage) {
+    return { basis, observedAt: null, generationTag: generationTag ?? null, counts: null, oldestCarried: null };
+  }
+  const eligible = (coverage.rows || []).filter((row) => row?.kind === 'repository' && row.disposition === 'eligible');
+  const count = (status) => eligible.filter((row) => row.status === status).length;
+  return {
+    basis,
+    observedAt: isoOrNull(coverage.observedAt),
+    generationTag: generationTag ?? null,
+    counts: {
+      eligible: eligible.length,
+      current: count('CURRENT'),
+      stale: count('STALE'),
+      missing: count('MISSING'),
+      unverified: count('UNVERIFIED'),
+      retired: fixtureStores ? retiredFixtureStores({ coverage, fixtureStores }).length : null,
+    },
+    oldestCarried: oldestCarriedOf(eligible),
+  };
+}