ruvnet-brain 4.2.2-dev → 4.3.1

package/scripts/public-verification-lane.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import osModule from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalJson, digest, validateCoverageLedger } from './coverage-integrity.mjs';
+import { validateHostRegistry } from './host-registry.mjs';
+import { RECEIPT_MODE_NAMES } from './host-install-matrix.mjs';
+import { generatePublicationReceipt, livePublicationAdapter } from './publication-receipt.mjs';
+import {
+  createPublicVerificationLeaf,
+  PUBLIC_VERIFICATION_MODES,
+  PUBLIC_VERIFICATION_OS,
+} from './public-verification-aggregate.mjs';
+import { transactionIdFor } from './release-transaction.mjs';
+import {
+  runRetrievalCanaries,
+  validatePlanAgainstCoverage,
+  validateRetrievalCanaryReceipt,
+} from './retrieval-canary.mjs';
+
+const HEX40 = /^[a-f0-9]{40}$/;
+const HEX64 = /^[a-f0-9]{64}$/;
+const normalizedDigest = (value) => String(value || '').replace(/^sha256:/, '');
+
+function validateReleaseIdentity(identity) {
+  if (identity?.repository !== 'stuinfla/ruvnet-brain' || identity?.package !== 'ruvnet-brain'
+    || !HEX40.test(String(identity.candidateSha || '')) || !HEX64.test(String(identity.payloadId || ''))
+    || !HEX64.test(String(identity.packageSha256 || '')) || !HEX64.test(String(identity.bundleSha256 || ''))
+    || typeof identity.version !== 'string' || !identity.version || identity.tag !== `v${identity.version}`) {
+    throw new Error('release transaction identity is malformed');
+  }
+  return identity;
+}
+
+function validatePublicEvidence({ candidate, publication, identity }) {
+  const candidateArtifact = normalizedDigest(candidate?.artifact?.sha256);
+  const surface = publication?.postPublicationChecks?.find(({ name }) => name === 'published-surface-probe');
+  if (candidate?.sha !== identity.candidateSha || candidate?.version !== identity.version || candidate?.tag !== identity.tag
+    || candidateArtifact !== identity.packageSha256 || publication?.sha !== identity.candidateSha
+    || publication?.version !== identity.version || publication?.payloadId !== identity.payloadId
+    || publication?.artifactSha256 !== identity.packageSha256
+    || publication?.bundleArtifactSha256 !== identity.bundleSha256
+    || publication?.npm?.version !== identity.version || publication?.npm?.sha !== identity.candidateSha
+    || publication?.npm?.artifactSha256 !== identity.packageSha256
+    || publication?.githubRelease?.tag !== identity.tag || publication?.githubRelease?.sha !== identity.candidateSha
+    || publication?.githubRelease?.artifactSha256 !== identity.packageSha256
+    || publication?.brain?.status !== 'PASS' || publication.brain.selfStore !== true
+    || surface?.status !== 'completed' || surface?.conclusion !== 'success' || surface?.sha !== identity.candidateSha) {
+    throw new Error('public byte identity or functional surface evidence differs from the release transaction');
+  }
+  return publication;
+}
+
+function coverageProjection(coverage) {
+  const checked = validateCoverageLedger(coverage);
+  if (!checked.valid || coverage.kind !== 'ruvnet-brain-release-coverage') {
+    throw new Error(`release coverage is invalid: ${checked.failures.join('; ')}`);
+  }
+  const repositories = coverage.rows.filter((row) => row.kind === 'repository' && row.disposition === 'eligible');
+  const gists = coverage.rows.filter((row) => row.kind === 'gist' && row.disposition === 'eligible');
+  const currentRepositories = repositories.filter(({ status }) => status === 'CURRENT').length;
+  const currentGists = gists.filter(({ status }) => status === 'CURRENT').length;
+  if (currentRepositories !== repositories.length || currentGists !== gists.length) {
+    throw new Error('release coverage contains a non-current eligible source');
+  }
+  return {
+    verified: true,
+    eligibleCurrent: currentRepositories,
+    eligibleTotal: repositories.length,
+    gistCurrent: currentGists,
+    gistTotal: gists.length,
+  };
+}
+
+export async function createPublicVerificationLane({
+  os,
+  candidate,
+  publication,
+  identity,
+  releaseCoverage,
+  coverageIdentity,
+  retrievalPlan,
+  hostRegistry,
+  adapter,
+} = {}) {
+  if (!PUBLIC_VERIFICATION_OS.includes(os)) throw new Error(`unsupported public verification OS: ${os || '(missing)'}`);
+  validateReleaseIdentity(identity);
+  validatePublicEvidence({ candidate, publication, identity });
+  const registry = validateHostRegistry(hostRegistry);
+  const coverage = coverageProjection(releaseCoverage);
+  if (!coverageIdentity || retrievalPlan?.coverage?.sha256 !== coverageIdentity.sha256
+    || retrievalPlan.coverage.bytes !== coverageIdentity.bytes
+    || releaseCoverage.releaseCoverageGeneration !== retrievalPlan.coverage.releaseCoverageGeneration) {
+    throw new Error('retrieval plan coverage byte identity differs');
+  }
+  validatePlanAgainstCoverage(retrievalPlan, releaseCoverage, { allowObservedBaseline: true });
+  if (retrievalPlan.candidate.sourceSha !== identity.candidateSha
+    || retrievalPlan.candidate.packageSha256 !== identity.packageSha256
+    || retrievalPlan.candidate.archiveSha256 !== identity.bundleSha256) {
+    throw new Error('retrieval plan candidate identity differs from the release transaction');
+  }
+  if (!adapter || typeof adapter.searchInstalled !== 'function'
+    || typeof adapter.resolveInstalledCitation !== 'function') {
+    throw new Error('public verification lane adapter is incomplete');
+  }
+  const common = {
+    sourceSha: identity.candidateSha,
+    version: identity.version,
+    tag: identity.tag,
+    artifactSha256: identity.packageSha256,
+    bundleSha256: identity.bundleSha256,
+    payloadId: identity.payloadId,
+    hostRegistryDigest: registry.registrySha256,
+    coverageGeneration: releaseCoverage.releaseCoverageGeneration,
+    canaryPlanSha256: retrievalPlan.planSha256,
+    releaseTransactionId: transactionIdFor(identity),
+  };
+  const leaves = [];
+  for (const mode of PUBLIC_VERIFICATION_MODES) {
+    const installed = publication.installed?.[RECEIPT_MODE_NAMES[mode]];
+    if (installed?.status !== 'PASS' || installed.doctorExit !== 0 || installed.version !== identity.version
+      || installed.artifactSha256 !== identity.packageSha256 || installed.functionalSearch !== true) {
+      throw new Error(`${os}/${mode} installed public loader evidence is incomplete`);
+    }
+    const retrieval = await runRetrievalCanaries({
+      plan: retrievalPlan,
+      sourceSha: identity.candidateSha,
+      artifactSha256: identity.packageSha256,
+      candidateArchiveSha256: identity.bundleSha256,
+      search: ({ query, k }) => adapter.searchInstalled({ mode, query, k }),
+      citationResolver: (matched, expected) => adapter.resolveInstalledCitation({ mode, matched, expected }),
+    });
+    const verifiedRetrieval = validateRetrievalCanaryReceipt(
+      retrieval,
+      { plan: retrievalPlan, requireAcceptance: true },
+    );
+    leaves.push(createPublicVerificationLeaf({
+      ...common,
+      os,
+      mode,
+      status: verifiedRetrieval.receiptSha256 === retrieval.receiptSha256 ? 'completed' : 'failed',
+      verdict: 'PASS',
+      publicBytes: { npmExact: true, githubExact: true, bundleExact: true },
+      installed: { version: installed.version, loaderVerified: true },
+      coverage,
+      retrievalPlan,
+      retrieval,
+      untested: [],
+      skipped: 0,
+      unknown: 0,
+    }));
+  }
+  if (canonicalJson(leaves.map(({ mode }) => mode)) !== canonicalJson(PUBLIC_VERIFICATION_MODES)) {
+    throw new Error('public verification lane modes are incomplete');
+  }
+  return leaves;
+}
+
+const hostOperatingSystem = () => ({ linux: 'linux', darwin: 'macos', win32: 'windows' })[process.platform] || null;
+
+function regularJson(file, label) {
+  const absolute = path.resolve(file || '');
+  let stat;
+  try { stat = fs.lstatSync(absolute); } catch { throw new Error(`${label} is missing`); }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${label} is not a trusted regular file`);
+  return { absolute, bytes: fs.readFileSync(absolute), value: JSON.parse(fs.readFileSync(absolute, 'utf8')) };
+}
+
+export async function generatePublicVerificationLane({
+  os,
+  candidatePath,
+  identityPath,
+  coveragePath,
+  planPath,
+  registryPath,
+  outPath,
+  root = process.cwd(),
+  adapter = livePublicationAdapter({ root }),
+} = {}) {
+  if (os !== hostOperatingSystem()) throw new Error(`runner OS ${hostOperatingSystem() || process.platform} cannot produce ${os || '(missing)'}`);
+  const candidate = regularJson(candidatePath, 'candidate receipt');
+  const identity = regularJson(identityPath, 'release identity');
+  const releaseCoverage = regularJson(coveragePath, 'release coverage');
+  const retrievalPlan = regularJson(planPath, 'retrieval plan');
+  const hostRegistry = regularJson(registryPath, 'host registry');
+  const output = path.resolve(outPath || '');
+  if (!outPath) throw new Error('--out is required');
+  if (fs.existsSync(output)) throw new Error(`refusing to overwrite public verification lane: ${output}`);
+  const temp = fs.mkdtempSync(path.join(osModule.tmpdir(), `ruvnet-public-${os}-`));
+  const publicationPath = path.join(temp, 'publication-receipt.json');
+  try {
+    await generatePublicationReceipt({ root, candidatePath: candidate.absolute, outPath: publicationPath,
+      adapter, disposeAdapter: false });
+    const publication = JSON.parse(fs.readFileSync(publicationPath, 'utf8'));
+    const leaves = await createPublicVerificationLane({
+      os,
+      candidate: candidate.value,
+      publication,
+      identity: identity.value,
+      releaseCoverage: releaseCoverage.value,
+      coverageIdentity: { sha256: crypto.createHash('sha256').update(releaseCoverage.bytes).digest('hex'),
+        bytes: releaseCoverage.bytes.length },
+      retrievalPlan: retrievalPlan.value,
+      hostRegistry: hostRegistry.value,
+      adapter,
+    });
+    const payload = { schemaVersion: 1, kind: 'ruvnet-brain-public-verification-os-lane', os, leaves };
+    const receipt = { ...payload, laneSha256: digest(payload) };
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.writeFileSync(output, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    return receipt;
+  } finally {
+    await adapter.dispose?.();
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function argument(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : null;
+}
+
+export async function main(args = process.argv.slice(2)) {
+  try {
+    const receipt = await generatePublicVerificationLane({
+      os: argument(args, '--os'),
+      candidatePath: argument(args, '--candidate'),
+      identityPath: argument(args, '--identity'),
+      coveragePath: argument(args, '--coverage'),
+      planPath: argument(args, '--plan'),
+      registryPath: argument(args, '--registry'),
+      outPath: argument(args, '--out'),
+    });
+    process.stdout.write(`${JSON.stringify({ ok: true, os: receipt.os, laneSha256: receipt.laneSha256 })}\n`);
+    return 0;
+  } catch (error) {
+    console.error(`public-verification-lane: ${error.message}`);
+    return 1;
+  }
+}
+
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) process.exitCode = await main();

package/scripts/publication-receipt.mjs

@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
+import readline from 'node:readline';
 import { spawn, spawnSync } from 'node:child_process';
 // ONE doctor rule and ONE mode vocabulary, shared with the staged-side check in
 // scripts/staged-host-verifier.mjs. This file kept its own copies, spelled claudeOnly/
@@ -18,6 +19,8 @@ import { HOST_MODES, RECEIPT_MODE_NAMES, MODE_FROM_RECEIPT_NAME, classifyDoctor,
 import { pathToFileURL } from 'node:url';
 import { evaluateCandidateReceipt, evaluatePublicationReceipt } from './release-proof.mjs';
 import { verifyPayload } from './release-payload.mjs';
+import { digest, sha256File } from './coverage-integrity.mjs';
+import { parseCitations } from '../kb/verify-citation.mjs';
 
 const REPO = 'stuinfla/ruvnet-brain';
 const PACKAGE = 'ruvnet-brain';
@@ -183,7 +186,8 @@ function rpcSearch(server, env, query, timeoutMs = DEADLINE_MS) {
 }
 
 export function livePublicationAdapter({ root = process.cwd() } = {}) {
-  let installContext = null;
+  const installContexts = new Map();
+  const passageFileDigests = new Map();
   let installTemp = null;
   return {
     async downloadNpm({ version, destination }) {
@@ -272,7 +276,7 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
           functionalSearch: true, searchMs: searched.broadMs, hostsOnPath: mode,
           ...verified,
         };
-        if (mode === 'dual') installContext = { temp, home, codexHome, brainHome, kb, env, packageRoot };
+        installContexts.set(MODE_FROM_RECEIPT_NAME[mode], { temp, home, codexHome, brainHome, kb, env, packageRoot });
       }
       return {
         ...results,
@@ -280,8 +284,9 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
       };
     },
 
-    async probeBrain() {
-      if (!installContext) throw new Error('public hosts must be installed before Brain proof');
+    async probeBrain({ mode = 'dual' } = {}) {
+      const installContext = installContexts.get(mode);
+      if (!installContext) throw new Error(`${mode} public host must be installed before Brain proof`);
       const rvfs = fs.readdirSync(installContext.kb).filter((name) => /ruvnet-brain.*\.rvf$/i.test(name));
       if (rvfs.length === 0) throw new Error('installed public Brain has no ruvnet-brain self RVF');
       const server = path.join(installContext.home, '.claude', 'ruvnet-brain', 'mcp', 'server.mjs');
@@ -292,6 +297,43 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
       return { status: 'PASS', selfStore: true, broadMs: result.broadMs, deadlineMs: DEADLINE_MS };
     },
 
+    async searchInstalled({ mode, query }) {
+      const context = installContexts.get(mode);
+      if (!context) throw new Error(`${mode} public host is not installed`);
+      const result = await rpcSearch(findMcpServer(context.home), context.env, query, DEADLINE_MS);
+      return parseCitations(result.text).map((citation) => ({
+        repo: citation.repo.toLowerCase(),
+        path: citation.docPath,
+      }));
+    },
+
+    async resolveInstalledCitation({ mode, matched, expected }) {
+      const context = installContexts.get(mode);
+      if (!context) throw new Error(`${mode} public host is not installed`);
+      if (String(matched?.repo || '').toLowerCase() !== expected.repo || matched?.path !== expected.path) {
+        return { resolved: false };
+      }
+      const files = [
+        path.join(context.kb, `${expected.repo}.passages.jsonl`),
+        path.join(context.kb, `${expected.repo}.big.passages.jsonl`),
+      ].filter((file) => fs.existsSync(file));
+      for (const file of files) {
+        const rows = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
+        try {
+          for await (const line of rows) {
+            let record;
+            try { record = JSON.parse(line); } catch { continue; }
+            if (record?.path !== expected.path) continue;
+            const passageSha256 = digest(record);
+            if (passageSha256 !== expected.passageSha256) return { resolved: false };
+            if (!passageFileDigests.has(file)) passageFileDigests.set(file, sha256File(file));
+            return { resolved: true, evidence: { passageSha256, passageFileSha256: passageFileDigests.get(file) } };
+          }
+        } finally { rows.close(); }
+      }
+      return { resolved: false };
+    },
+
     async probePublishedSurface({ sha }) {
       const head = command('git', ['rev-parse', 'HEAD'], { cwd: root });
       if (head !== sha) throw new Error(`published-surface probe checkout ${head} does not match candidate ${sha}`);
@@ -307,7 +349,8 @@ export function livePublicationAdapter({ root = process.cwd() } = {}) {
     async dispose() {
       if (installTemp) fs.rmSync(installTemp, { recursive: true, force: true });
       installTemp = null;
-      installContext = null;
+      installContexts.clear();
+      passageFileDigests.clear();
     },
   };
 }
@@ -317,6 +360,7 @@ export async function generatePublicationReceipt({
   candidatePath,
   outPath,
   adapter = livePublicationAdapter({ root }),
+  disposeAdapter = true,
 } = {}) {
   if (!candidatePath || !outPath) throw new Error('candidatePath and outPath are required');
   if (fs.existsSync(outPath)) throw new Error(`refusing to overwrite existing publication receipt: ${outPath}`);
@@ -386,7 +430,7 @@ export async function generatePublicationReceipt({
     fs.writeFileSync(outPath, `${JSON.stringify(publication, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
     return result;
   } finally {
-    await adapter.dispose?.();
+    if (disposeAdapter) await adapter.dispose?.();
     fs.rmSync(temp, { recursive: true, force: true });
   }
 }

package/scripts/rebuild-gists-from-receipts.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-// Deterministically reconstruct gist passages from tracked, exact-version source receipts.
+// Deterministically reconstruct gist passages from durable, exact-version source receipts.
 // This intentionally does not call the GitHub API, build vectors, or publish artifacts.
 
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { sealGistReceiptSet, validateGistReceiptSet } from './gist-receipts.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const NAME = 'ruv-gists';
@@ -32,6 +34,19 @@ function validateFilename(filename, label) {
 }
 
 export function validateSourceReceipts(source) {
+  if (source?.schemaVersion === 3) {
+    const observation = {
+      owner: source.owner,
+      observedAt: source.observedAt,
+      observationSha256: source.sourceObservationSha256,
+      gists: { rows: Object.entries(source.gists || {}).map(([id, receipt]) => ({
+        id, updated_at: receipt?.updatedAt,
+      })) },
+    };
+    try { validateGistReceiptSet(source, observation); }
+    catch (error) { fail(`schema-3 source receipt is invalid: ${error.message}`); }
+    return source;
+  }
   if (![1, 2].includes(source?.schemaVersion)) fail('source receipt schemaVersion must be 1 or 2');
   if (!/^[A-Za-z0-9-]{1,39}$/.test(String(source.owner || ''))) fail('source receipt owner is malformed');
   if (!validDate(source.generated)) fail('source receipt generated timestamp is malformed');
@@ -177,11 +192,14 @@ export async function reconstructGists(source, { fetchFn = globalThis.fetch, con
     note: "rUv's public gists — announcements and thinking, PROPOSED unless confirmed in repo source.",
     entries,
   };
+  const passagesSha256 = sha256(passageBody);
   return {
     passages,
     passageBody,
     meta,
-    sources: { ...source, schemaVersion: 2, passagesSha256: sha256(passageBody), gists: source.gists },
+    sources: source.schemaVersion === 3
+      ? sealGistReceiptSet({ ...source, passagesSha256 })
+      : { ...source, schemaVersion: 2, passagesSha256, gists: source.gists },
   };
 }
 
@@ -218,12 +236,39 @@ function option(argv, name, fallback) {
   return index >= 0 && argv[index + 1] && !argv[index + 1].startsWith('--') ? argv[index + 1] : fallback;
 }
 
-export async function main(argv = process.argv.slice(2)) {
+/**
+ * The receipt belongs beside the installed brain, because a published npm package intentionally
+ * does not contain the 300KB generated receipt. Prefer a source-checkout copy when one exists, then
+ * honor the canonical brain-root overrides, then use the standard installed cache. Returning the
+ * checkout candidate on a total miss preserves one precise error path instead of guessing.
+ */
+export function resolveSourcesFile({
+  repoRoot = ROOT,
+  env = process.env,
+  home = os.homedir(),
+  exists = fs.existsSync,
+} = {}) {
+  const local = path.join(repoRoot, 'kb', `${NAME}.sources.json`);
+  const candidates = [
+    local,
+    env.RUVNET_BRAIN_KB && path.join(env.RUVNET_BRAIN_KB, `${NAME}.sources.json`),
+    env.RUVNET_BRAIN_HOME && path.join(env.RUVNET_BRAIN_HOME, 'kb', `${NAME}.sources.json`),
+    path.join(home, '.cache', 'ruvnet-brain', 'kb', `${NAME}.sources.json`),
+  ].filter(Boolean).map((candidate) => path.resolve(candidate));
+  return candidates.find((candidate) => exists(candidate)) || local;
+}
+
+export async function main(argv = process.argv.slice(2), {
+  fetchFn = globalThis.fetch,
+  repoRoot = ROOT,
+  env = process.env,
+  home = os.homedir(),
+} = {}) {
   const allowed = new Set(['--sources', '--out-dir', '--concurrency']);
   for (let index = 0; index < argv.length; index += 2) {
     if (!allowed.has(argv[index]) || !argv[index + 1] || argv[index + 1].startsWith('--')) fail(`unknown or incomplete option ${argv[index] || '(missing)'}`);
   }
-  const sourcesFile = path.resolve(option(argv, '--sources', path.join(ROOT, 'kb', `${NAME}.sources.json`)));
+  const sourcesFile = path.resolve(option(argv, '--sources', resolveSourcesFile({ repoRoot, env, home })));
   const outDir = path.resolve(option(argv, '--out-dir', path.dirname(sourcesFile)));
   const concurrency = Number(option(argv, '--concurrency', '6'));
   let source;
@@ -232,7 +277,7 @@ export async function main(argv = process.argv.slice(2)) {
   } catch (error) {
     fail(`cannot read source receipts ${sourcesFile}: ${error.message}`);
   }
-  const result = await reconstructGists(source, { concurrency });
+  const result = await reconstructGists(source, { concurrency, fetchFn });
   const written = writeReconstruction(result, { outDir });
   process.stdout.write(`${JSON.stringify({ ok: true, passages: result.passages.length, passagesSha256: result.sources.passagesSha256, ...written }, null, 2)}\n`);
   return 0;

package/scripts/release-projection.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Build the release-bound coverage projection from an observed corpus ledger and exact bundle bytes.
+// This is intentionally a producer, not a validator: public-verification-inputs.mjs remains the
+// independent consumer that proves the emitted files agree with the archive.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { digest, generationLedgerBytes, projectPublicGenerationLedger,
+  releaseCoverageGenerationFor } from '../plugin/scripts/coverage-integrity.mjs';
+import { validatePublicInventory } from './public-inventory.mjs';
+import { readRvfGenerations } from './rvf-generation.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (name, fallback = null) => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : fallback; };
+const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const storeName = (value) => String(value || '').toLowerCase().replace(/\.big\.rvf$|\.rvf$/i, '');
+
+export function createReleaseProjection({ corpusCoverage, assetsDir, version, sourceSnapshot,
+  corpusSeed, baselineReceiptSha256, outDir }) {
+  if (!corpusCoverage || corpusCoverage.kind !== 'ruvnet-brain-corpus-coverage') {
+    throw new Error('corpus coverage must be an observed ruvnet-brain-corpus-coverage ledger');
+  }
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version || '')) throw new Error('release version is invalid');
+  if (!/^[a-f0-9]{40}$/.test(sourceSnapshot || '')) throw new Error('release source snapshot is invalid');
+  if (!corpusSeed?.tag || !/^[a-f0-9]{64}$/.test(corpusSeed.archiveSha256 || '')
+    || !Number.isSafeInteger(corpusSeed.archiveBytes) || !/^[a-f0-9]{64}$/.test(baselineReceiptSha256 || '')) {
+    throw new Error('corpus seed identity is incomplete');
+  }
+  const assets = path.resolve(assetsDir);
+  const sourceLedger = readRvfGenerations(assets);
+  // The coverage ledger describes the full upstream universe. A release candidate contains
+  // only the immutable seed's asset set, so absent-but-eligible upstream rows are not release
+  // blockers; shipped stores must still all be CURRENT.
+  const assetStores = fs.readdirSync(assets)
+    .filter((name) => /\.rvf$/i.test(name)).map(storeName);
+  const availableStores = new Set([
+    ...Object.keys(sourceLedger.stores || {}).map(storeName),
+    ...assetStores,
+  ]);
+  const eligible = corpusCoverage.rows.filter((row) => row.disposition === 'eligible'
+    && availableStores.has(storeName(row.artifact?.store)));
+  if (!eligible.length || eligible.some((row) => row.status !== 'CURRENT')) throw new Error('eligible corpus rows are not all CURRENT');
+  const publicStores = [...new Set(eligible.map((row) => String(row.artifact.store).toLowerCase()))];
+  // Derived public stores are not corpus rows, but they are still part of the
+  // exact shipped generation ledger when the candidate asset set contains them.
+  if (sourceLedger.stores?.concepts && !publicStores.includes('concepts')) publicStores.push('concepts');
+  const ledger = projectPublicGenerationLedger({ ledger: sourceLedger, publicStores, version, sourceSnapshot });
+  const releaseBase = {
+    schemaVersion: 1, kind: 'ruvnet-brain-release-coverage', owner: corpusCoverage.owner,
+    observedAt: corpusCoverage.observedAt, generatorSourceSha: corpusCoverage.generatorSourceSha,
+    sourceObservationSha256: corpusCoverage.sourceObservationSha256, snapshotRoot: corpusCoverage.snapshotRoot,
+    releaseIdentity: { version, tag: `v${version}`, sourceSnapshot },
+    corpusSeed: { tag: corpusSeed.tag, archiveSha256: corpusSeed.archiveSha256,
+      archiveBytes: corpusSeed.archiveBytes, receiptSha256: baselineReceiptSha256 },
+    corpusCoverage: { sha256: sha256(Buffer.from(`${JSON.stringify(corpusCoverage, null, 2)}\n`)), coverageGeneration: corpusCoverage.coverageGeneration },
+    generationLedger: { file: 'PUBLIC-RVF-GENERATIONS.json', sha256: sha256(generationLedgerBytes(ledger)),
+      bytes: generationLedgerBytes(ledger).length, storeCount: Object.keys(ledger.stores).length },
+    installedProjectionSchema: 2, policy: corpusCoverage.policy, enumerationReceipt: corpusCoverage.enumerationReceipt,
+    rows: corpusCoverage.rows, totals: corpusCoverage.totals,
+  };
+  const inventory = validatePublicInventory({ assetsDir: assets, coverage: releaseBase, ledger });
+  releaseBase.publicInventoryPartitionSha256 = inventory.partitionSha256;
+  releaseBase.releaseCoverageGeneration = releaseCoverageGenerationFor(releaseBase);
+  const out = path.resolve(outDir);
+  fs.mkdirSync(out, { recursive: true });
+  const corpusBytes = Buffer.from(`${JSON.stringify(corpusCoverage, null, 2)}\n`);
+  const coverageBytes = Buffer.from(`${JSON.stringify(releaseBase, null, 2)}\n`);
+  fs.writeFileSync(path.join(out, 'CORPUS-COVERAGE.json'), corpusBytes);
+  fs.writeFileSync(path.join(out, 'COVERAGE.json'), coverageBytes);
+  fs.writeFileSync(path.join(out, 'PUBLIC-RVF-GENERATIONS.json'), generationLedgerBytes(ledger));
+  return releaseBase;
+}
+
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) {
+  try {
+    const corpusFile = path.resolve(arg('--corpus', path.join(ROOT, 'data', 'source-coverage.json')));
+    const corpus = readJson(corpusFile);
+    const projection = createReleaseProjection({ corpusCoverage: corpus,
+      assetsDir: arg('--assets'), outDir: arg('--out', 'release-evidence'), version: arg('--version'),
+      sourceSnapshot: arg('--source-snapshot'), baselineReceiptSha256: arg('--baseline-receipt-sha256'),
+      corpusSeed: { tag: arg('--seed-tag'), archiveSha256: arg('--seed-sha256'), archiveBytes: Number(arg('--seed-bytes')) } });
+    console.log(JSON.stringify({ ok: true, releaseCoverageGeneration: projection.releaseCoverageGeneration }));
+  } catch (error) { console.error(`[release-projection] ${error.message}`); process.exitCode = 1; }
+}