ruvnet-brain 4.0.36 → 4.2.2-dev

package/scripts/corpus-candidate.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// Seal and independently verify the exact public corpus bytes used by a release.
+
+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 } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REQUIRED_SUFFIXES = [
+  '.big.rvf',
+  '.big.rvf.idmap.json',
+  '.big.rvf.embed.json',
+  '.passages.jsonl',
+  '.meta.json',
+];
+const OPTIONAL_SHIPPED_SUFFIXES = ['.big.passages.jsonl', '.big.meta.json'];
+
+function fail(message) {
+  throw new Error(`[corpus-candidate] ${message}`);
+}
+
+function readJson(file, label) {
+  if (!file || !fs.existsSync(file)) fail(`${label} missing (${file || 'no path supplied'})`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail(`${label} unreadable/corrupt (${error.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');
+}
+
+function fileIdentity(file) {
+  return { file: path.basename(file), sha256: sha256File(file), bytes: fs.statSync(file).size };
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function policyRows(policy) {
+  if (Array.isArray(policy)) return policy;
+  for (const key of ['sources', 'rows', 'repositories', 'repos']) {
+    if (Array.isArray(policy?.[key])) return policy[key];
+  }
+  return [];
+}
+
+function assertPolicyCurrent(policy) {
+  const rows = policyRows(policy);
+  const stale = rows.filter((row) => row?.eligible !== false && row?.status !== 'CURRENT');
+  if (stale.length) fail(`eligibility policy has ${stale.length} eligible row(s) that are not CURRENT`);
+  return {
+    eligibleRepoCount: rows.filter((row) => row?.eligible !== false && row?.status === 'CURRENT').length,
+    gistCount: rows.filter((row) => /gist/i.test(String(row?.kind || row?.type || ''))).length,
+  };
+}
+
+function archiveEntries(bundleFile) {
+  const result = spawnSync('unzip', ['-Z1', bundleFile], { encoding: 'utf8' });
+  if (result.status !== 0) fail(`cannot list archive (${result.stderr.trim() || `exit ${result.status}`})`);
+  const entries = result.stdout.split(/\r?\n/).filter(Boolean);
+  for (const entry of entries) {
+    const normalized = entry.replaceAll('\\', '/');
+    if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+      fail(`archive contains unsafe path ${JSON.stringify(entry)}`);
+    }
+  }
+  return entries;
+}
+
+function verifyArchive({ bundleFile, stores, privateStores }) {
+  if (!bundleFile || !fs.existsSync(bundleFile)) fail(`bundle missing (${bundleFile || 'no path supplied'})`);
+  const entries = archiveEntries(bundleFile);
+  for (const privateStore of privateStores) {
+    const escaped = privateStore.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const privateFile = new RegExp(`(?:^|/)${escaped}(?:\\.|$)`, 'i');
+    if (entries.some((entry) => privateFile.test(entry))) fail(`private store ${privateStore} is present in archive`);
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-candidate-'));
+  try {
+    const extraction = spawnSync('unzip', ['-qq', bundleFile, '-d', tmp], { encoding: 'utf8' });
+    if (extraction.status !== 0) fail(`cannot extract archive (${extraction.stderr.trim() || `exit ${extraction.status}`})`);
+    for (const store of stores) {
+      for (const expected of store.files) {
+        const matches = entries.filter((entry) => path.posix.basename(entry) === expected.file);
+        if (matches.length !== 1) fail(`archive must contain exactly one ${expected.file}; found ${matches.length}`);
+        const extracted = path.join(tmp, ...matches[0].replaceAll('\\', '/').split('/'));
+        if (sha256File(extracted) !== expected.sha256) fail(`archive ${expected.file} differs from canonical assets`);
+      }
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+  return fileIdentity(bundleFile);
+}
+
+function buildReceipt({
+  assetsDir,
+  bundleFile,
+  policyFile,
+  builderSourceSha,
+  createdAt,
+}) {
+  const assets = path.resolve(assetsDir || '');
+  if (!fs.existsSync(assets) || !fs.statSync(assets).isDirectory()) fail(`assets directory missing (${assets})`);
+  if (!/^[a-f0-9]{40,64}$/i.test(builderSourceSha || '')) fail('builderSourceSha must be a 40-64 hex source identity');
+
+  const fenceFile = path.join(assets, 'PRIVATE-STORES.json');
+  const fence = readJson(fenceFile, 'private fence');
+  if (!Array.isArray(fence.privateStores)) fail('private fence has no privateStores array');
+  const privateStores = [...new Set(fence.privateStores.map((name) => String(name).toLowerCase()))].sort();
+  const privateSet = new Set(privateStores);
+  const ledgerFile = path.join(assets, 'RVF-GENERATIONS.json');
+  const ledger = readJson(ledgerFile, 'RVF generation ledger');
+  if (!ledger.stores || typeof ledger.stores !== 'object' || Array.isArray(ledger.stores)) {
+    fail('RVF generation ledger has no stores object');
+  }
+  const policy = readJson(path.resolve(policyFile || ''), 'eligibility policy');
+  const counts = assertPolicyCurrent(policy);
+
+  const rvfFiles = fs.readdirSync(assets).filter((name) => /^.+\.big\.rvf$/.test(name)).sort();
+  const rvfByStore = new Map(rvfFiles.map((file) => [file.slice(0, -'.big.rvf'.length), file]));
+  const unreceipted = [...rvfByStore.keys()].filter((store) => !ledger.stores[store]);
+  if (unreceipted.length) fail(`unreceipted RVF files: ${unreceipted.join(', ')}`);
+  const orphanLedger = Object.entries(ledger.stores)
+    .filter(([store, generation]) => generation.file !== `${store}.big.rvf` || !rvfByStore.has(store))
+    .map(([store]) => store);
+  if (orphanLedger.length) fail(`ledger rows without RVFs: ${orphanLedger.join(', ')}`);
+
+  const digestOwners = new Map();
+  for (const [store, file] of rvfByStore) {
+    const digest = sha256File(path.join(assets, file));
+    const owners = digestOwners.get(digest) || [];
+    owners.push(store);
+    digestOwners.set(digest, owners);
+  }
+  const duplicateRvfDigests = [...digestOwners.entries()]
+    .filter(([, owners]) => owners.length > 1)
+    .map(([sha256, owners]) => ({ sha256, stores: owners.sort() }));
+  if (duplicateRvfDigests.length) fail(`duplicate RVF bytes: ${duplicateRvfDigests.map((row) => row.stores.join('/')).join(', ')}`);
+
+  const missingSidecars = [];
+  const stores = [];
+  for (const [store, rvfFile] of [...rvfByStore].sort(([a], [b]) => a.localeCompare(b))) {
+    const generation = ledger.stores[store];
+    const rvfPath = path.join(assets, rvfFile);
+    if (generation.file !== rvfFile || generation.sha256 !== sha256File(rvfPath) || generation.bytes !== fs.statSync(rvfPath).size) {
+      fail(`${store}: generation receipt does not match RVF bytes`);
+    }
+    if (!generation.sourceCommit || !generation.builtUtc || !generation.model || !Number.isInteger(generation.dimensions)) {
+      fail(`${store}: generation receipt lacks sourceCommit, builtUtc, model, or dimensions provenance`);
+    }
+    if (privateSet.has(store.toLowerCase())) continue;
+    const files = [];
+    for (const suffix of REQUIRED_SUFFIXES) {
+      const file = path.join(assets, `${store}${suffix}`);
+      if (!fs.existsSync(file)) missingSidecars.push(path.basename(file));
+      else files.push(fileIdentity(file));
+    }
+    for (const suffix of OPTIONAL_SHIPPED_SUFFIXES) {
+      const file = path.join(assets, `${store}${suffix}`);
+      if (fs.existsSync(file)) files.push(fileIdentity(file));
+    }
+    stores.push({
+      name: store,
+      sourceCommit: generation.sourceCommit,
+      builtUtc: generation.builtUtc,
+      model: generation.model,
+      dimensions: generation.dimensions,
+      files,
+    });
+  }
+  if (missingSidecars.length) fail(`missing sidecars: ${missingSidecars.join(', ')}`);
+  if (!stores.length) fail('zero public corpus stores remain after the private fence');
+  const archive = verifyArchive({ bundleFile: path.resolve(bundleFile || ''), stores, privateStores });
+  const policyIdentity = fileIdentity(path.resolve(policyFile));
+  const fenceIdentity = fileIdentity(fenceFile);
+  const ledgerIdentity = fileIdentity(ledgerFile);
+  const coverageGeneration = String(policy.coverageGeneration || policy.generation || policy.generated || policyIdentity.sha256);
+
+  return {
+    schemaVersion: 1,
+    kind: 'ruvnet-brain-corpus-candidate',
+    builderSourceSha: builderSourceSha.toLowerCase(),
+    createdAt,
+    coverageGeneration,
+    eligibleRepoCount: counts.eligibleRepoCount,
+    gistCount: counts.gistCount,
+    storeCount: stores.length,
+    stores,
+    privateFence: fenceIdentity,
+    eligibilityPolicy: policyIdentity,
+    generationLedger: ledgerIdentity,
+    excludedPrivateStores: privateStores.filter((privateStore) =>
+      [...rvfByStore.keys()].some((store) => store.toLowerCase() === privateStore)),
+    duplicateRvfDigests,
+    unreceiptedRvfFiles: [],
+    missingSidecars: [],
+    archive,
+    generator: { corpusCandidateSha256: sha256File(fileURLToPath(import.meta.url)) },
+  };
+}
+
+function currentGitSha() {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: path.resolve(HERE, '..'), encoding: 'utf8' });
+  if (result.status !== 0) fail('cannot determine builder source SHA');
+  return result.stdout.trim();
+}
+
+export function createCorpusReceipt(options) {
+  const receiptFile = path.resolve(options.receiptFile || 'dist/corpus-receipt.json');
+  const receipt = buildReceipt({
+    ...options,
+    builderSourceSha: options.builderSourceSha || currentGitSha(),
+    createdAt: options.createdAt || new Date().toISOString(),
+  });
+  fs.mkdirSync(path.dirname(receiptFile), { recursive: true });
+  fs.writeFileSync(receiptFile, `${JSON.stringify(receipt, null, 2)}\n`, { flag: options.overwrite === false ? 'wx' : 'w' });
+  return receipt;
+}
+
+export function verifyCorpusReceipt(options) {
+  const receipt = readJson(path.resolve(options.receiptFile || ''), 'corpus receipt');
+  if (receipt.kind !== 'ruvnet-brain-corpus-candidate' || receipt.schemaVersion !== 1) fail('unsupported corpus receipt');
+  const exactFiles = [
+    ['archive', path.resolve(options.bundleFile || '')],
+    ['eligibility policy', path.resolve(options.policyFile || '')],
+    ['private fence', path.join(path.resolve(options.assetsDir || ''), 'PRIVATE-STORES.json')],
+    ['generation ledger', path.join(path.resolve(options.assetsDir || ''), 'RVF-GENERATIONS.json')],
+  ];
+  for (const [label, file] of exactFiles) {
+    if (!fs.existsSync(file)) fail(`${label} missing (${file})`);
+    const expected = label === 'archive'
+      ? receipt.archive
+      : label === 'eligibility policy'
+        ? receipt.eligibilityPolicy
+        : label === 'private fence'
+          ? receipt.privateFence
+          : receipt.generationLedger;
+    if (sha256File(file) !== expected?.sha256) fail(`${label} sha256 differs from receipt`);
+    if (fs.statSync(file).size !== expected?.bytes) fail(`${label} byte length differs from receipt`);
+  }
+  const actual = buildReceipt({
+    ...options,
+    builderSourceSha: receipt.builderSourceSha,
+    createdAt: receipt.createdAt,
+  });
+  if (canonicalJson(actual) !== canonicalJson(receipt)) fail('receipt does not match the exact corpus inputs');
+  return receipt;
+}
+
+function arg(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+async function main() {
+  const mode = process.argv.includes('--verify') ? 'verify' : 'create';
+  const options = {
+    assetsDir: arg('--assets', 'kb'),
+    bundleFile: arg('--bundle', 'dist/ruvnet-brain.zip'),
+    policyFile: arg('--policy'),
+    receiptFile: arg('--receipt', arg('--out', 'dist/corpus-receipt.json')),
+    builderSourceSha: arg('--builder-source-sha'),
+  };
+  const receipt = mode === 'verify' ? verifyCorpusReceipt(options) : createCorpusReceipt(options);
+  console.log(JSON.stringify({ ok: true, mode, archive: receipt.archive, stores: receipt.storeCount }, null, 2));
+}
+
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/scripts/corpus-reconcile.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+// Build a corpus candidate from one immutable seed and exact upstream repository SHAs.
+// This module deliberately has no publication capability. The protected-release workflow owns
+// the only legal call to corpus-seed-publish.mjs.
+
+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 { extractZip } from '../kb/zip-extract.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = path.resolve(HERE, '..');
+const HEX40 = /^[0-9a-f]{40}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+const SAFE_STORE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function fail(message) {
+  throw new Error(`[corpus-reconcile] ${message}`);
+}
+
+function sha256File(file) {
+  if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) fail(`seed archive missing (${file || 'no path supplied'})`);
+  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');
+}
+
+function readJson(file, label) {
+  if (!file || !fs.existsSync(file)) fail(`${label} missing (${file || 'no path supplied'})`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail(`${label} unreadable (${error.message})`);
+  }
+}
+
+export function assertBootstrapIdentity({ archiveFile, tag, sha256, allowPinnedTag = false }) {
+  const expected = String(sha256 || '').toLowerCase();
+  if (!HEX64.test(expected) || (!allowPinnedTag && tag !== `corpus-sha256-${expected}`) || !tag || tag === 'latest') {
+    fail('bootstrap requires the exact digest-derived tag corpus-sha256-<configured sha256>; latest is forbidden');
+  }
+  const actual = sha256File(path.resolve(archiveFile || ''));
+  if (actual !== expected) fail(`downloaded archive sha256 ${actual} differs from configured ${expected}`);
+  return { tag, sha256: expected };
+}
+
+function filesNamed(root, wanted) {
+  const found = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && entry.name === wanted) found.push(file);
+    }
+  };
+  visit(root);
+  return found;
+}
+
+export function normalizeExtractedCorpus({ extractedDir, assetsDir }) {
+  const extracted = path.resolve(extractedDir || '');
+  const assets = path.resolve(assetsDir || '');
+  if (!fs.existsSync(extracted) || !fs.statSync(extracted).isDirectory()) {
+    fail(`extracted seed directory missing (${extracted})`);
+  }
+  if (fs.existsSync(assets) && fs.readdirSync(assets).length) fail(`bootstrap assets directory is not empty (${assets})`);
+  const ledgers = filesNamed(extracted, 'RVF-GENERATIONS.json');
+  if (ledgers.length !== 1) fail(`seed archive must contain exactly one RVF-GENERATIONS.json; found ${ledgers.length}`);
+  const corpusRoot = path.dirname(ledgers[0]);
+  if (fs.existsSync(path.join(corpusRoot, 'PRIVATE-STORES.json'))) {
+    fail('a published seed must not supply a private-store fence; the exact builder checkout owns that policy');
+  }
+  fs.mkdirSync(assets, { recursive: true });
+  for (const entry of fs.readdirSync(corpusRoot)) fs.renameSync(path.join(corpusRoot, entry), path.join(assets, entry));
+  return assets;
+}
+
+function repositorySlug(url) {
+  const match = String(url || '').match(/^https:\/\/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?$/i);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+export function planReconciliation({ coverage, ledger, assetsDir = null }) {
+  if (coverage?.schemaVersion !== 1 || !Array.isArray(coverage.rows) || !coverage.coverageGeneration) {
+    fail('coverage policy is missing a supported complete generation');
+  }
+  if (!ledger?.stores || typeof ledger.stores !== 'object' || Array.isArray(ledger.stores)) {
+    fail('RVF generation ledger has no stores object');
+  }
+  const eligible = coverage.rows.filter((row) => row?.kind === 'repository' && row?.disposition === 'eligible');
+  const seen = new Set();
+  const plan = [];
+  for (const row of eligible) {
+    const store = String(row?.artifact?.store || '');
+    if (!SAFE_STORE.test(store)) fail(`${row?.name || row?.key || 'eligible repository'} has an unsafe or missing store name`);
+    const folded = store.toLowerCase();
+    if (seen.has(folded)) fail(`duplicate eligible store ${store} in coverage policy`);
+    seen.add(folded);
+    const upstreamSha = String(row?.upstream?.sha || '').toLowerCase();
+    if (!HEX40.test(upstreamSha)) fail(`${row?.name || store} has a missing or malformed upstream SHA`);
+    if (!repositorySlug(row.url)) fail(`${row?.name || store} has no exact GitHub repository URL`);
+    const generation = Object.entries(ledger.stores).find(([name]) => name.toLowerCase() === folded)?.[1] || null;
+    const current = String(generation?.sourceCommit || '').toLowerCase();
+    let reason = generation?.sourceCommit ? 'sourceCommit differs' : 'missing ledger receipt';
+    if (current === upstreamSha) {
+      if (!assetsDir) continue;
+      const expectedFile = `${store}.big.rvf`;
+      const rvfFile = path.join(path.resolve(assetsDir), expectedFile);
+      const receiptMatches = generation?.file === expectedFile
+        && fs.existsSync(rvfFile)
+        && generation?.bytes === fs.statSync(rvfFile).size
+        && generation?.sha256 === sha256File(rvfFile);
+      if (receiptMatches) continue;
+      reason = 'generation receipt differs from seed bytes';
+    }
+    plan.push({
+      name: String(row.name || store),
+      store,
+      url: row.url,
+      upstreamSha,
+      ledgerSourceCommit: generation?.sourceCommit || null,
+      reason,
+    });
+  }
+  return plan.sort((a, b) => a.store.localeCompare(b.store));
+}
+
+function defaultRun(command, args, options = {}) {
+  return spawnSync(command, args, { encoding: 'utf8', ...options });
+}
+
+function checked(run, command, args, options = {}) {
+  const result = run(command, args, options) || {};
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || result.error?.message || `exit ${result.status}`).trim();
+    fail(`${command} ${args.join(' ')} failed${detail ? ` (${detail})` : ''}`);
+  }
+  return result;
+}
+
+export function executeReconciliation({
+  plan,
+  assetsDir,
+  workspaceDir,
+  root = DEFAULT_ROOT,
+  run = defaultRun,
+}) {
+  if (!Array.isArray(plan)) fail('reconciliation plan must be an array');
+  const assets = path.resolve(assetsDir || '');
+  const workspace = path.resolve(workspaceDir || '');
+  const ledgerFile = path.join(assets, 'RVF-GENERATIONS.json');
+  if (!fs.existsSync(ledgerFile)) fail(`RVF generation ledger missing (${ledgerFile})`);
+  if (fs.existsSync(workspace) && fs.readdirSync(workspace).length) fail(`fresh-clone workspace is not empty (${workspace})`);
+  fs.mkdirSync(workspace, { recursive: true });
+  const forge = path.join(path.resolve(root), 'kb', 'forge-refresh.mjs');
+  if (!fs.existsSync(forge)) fail(`forge-refresh missing (${forge})`);
+  const refreshed = [];
+
+  for (const item of plan) {
+    if (!SAFE_STORE.test(item.store) || !HEX40.test(item.upstreamSha) || !repositorySlug(item.url)) {
+      fail(`unsafe reconciliation item for ${item?.store || item?.name || 'unknown store'}`);
+    }
+    const cloneDir = path.join(workspace, item.store);
+    if (fs.existsSync(cloneDir)) fail(`fresh clone target already exists (${cloneDir})`);
+    checked(run, 'git', ['clone', '--no-checkout', '--filter=blob:none', item.url, cloneDir]);
+    checked(run, 'git', ['-C', cloneDir, 'fetch', '--depth=1', 'origin', item.upstreamSha]);
+    checked(run, 'git', ['-C', cloneDir, 'checkout', '--detach', 'FETCH_HEAD']);
+    const head = checked(run, 'git', ['-C', cloneDir, 'rev-parse', 'HEAD']);
+    if (String(head.stdout || '').trim().toLowerCase() !== item.upstreamSha) {
+      fail(`${item.store}: fresh clone did not resolve the exact upstream SHA`);
+    }
+    checked(run, process.execPath, [forge, '--repo', cloneDir, '--out', assets, '--name', item.store], { stdio: 'inherit' });
+    const ledger = readJson(ledgerFile, 'RVF generation ledger after forge-refresh');
+    const generation = Object.entries(ledger.stores || {}).find(([name]) => name.toLowerCase() === item.store.toLowerCase())?.[1];
+    if (String(generation?.sourceCommit || '').toLowerCase() !== item.upstreamSha) {
+      fail(`forge-refresh did not bind ${item.store} to the exact upstream SHA`);
+    }
+    refreshed.push(item.store);
+  }
+  return { refreshed };
+}
+
+export function prepareCorpusCandidate({
+  root = DEFAULT_ROOT,
+  assetsDir,
+  owner = 'ruvnet',
+  builderSha,
+  candidateDir,
+  receiptFile,
+  coverageFile,
+  run = defaultRun,
+}) {
+  const sourceRoot = path.resolve(root);
+  const assets = path.resolve(assetsDir || '');
+  const candidate = path.resolve(candidateDir || path.join(sourceRoot, 'dist', 'corpus-candidate'));
+  const receipt = path.resolve(receiptFile || path.join(sourceRoot, 'dist', 'corpus-receipt.json'));
+  const policy = path.resolve(coverageFile || path.join(sourceRoot, 'data', 'source-coverage.json'));
+  if (!HEX40.test(String(builderSha || '').toLowerCase())) fail('builder SHA must be exact 40-character lowercase hex');
+  const expectedPolicy = path.join(sourceRoot, 'data', 'source-coverage.json');
+  if (policy !== expectedPolicy) fail(`coverage policy must be the generator's canonical projection (${expectedPolicy})`);
+  const coverageScript = path.join(sourceRoot, 'scripts', 'source-coverage.mjs');
+  const buildScript = path.join(sourceRoot, 'scripts', 'build-bundle.mjs');
+  const receiptScript = path.join(sourceRoot, 'scripts', 'corpus-candidate.mjs');
+  for (const required of [coverageScript, buildScript, receiptScript]) {
+    if (!fs.existsSync(required)) fail(`required candidate builder missing (${required})`);
+  }
+  fs.mkdirSync(path.dirname(candidate), { recursive: true });
+  fs.mkdirSync(path.dirname(receipt), { recursive: true });
+  checked(run, process.execPath, [coverageScript, '--owner', owner, '--assets', assets, '--write'], { stdio: 'inherit' });
+  checked(run, process.execPath, [coverageScript, '--owner', owner, '--assets', assets, '--check', '--strict'], { stdio: 'inherit' });
+  checked(run, process.execPath, [buildScript, '--assets', assets, '--out', candidate], { stdio: 'inherit' });
+  const bundleFile = path.join(path.dirname(candidate), `${path.basename(candidate)}.zip`);
+  checked(run, process.execPath, [receiptScript, '--assets', assets, '--bundle', bundleFile,
+    '--policy', policy, '--receipt', receipt, '--builder-source-sha', builderSha], { stdio: 'inherit' });
+  checked(run, process.execPath, [receiptScript, '--verify', '--assets', assets, '--bundle', bundleFile,
+    '--policy', policy, '--receipt', receipt], { stdio: 'inherit' });
+  return { bundleFile, receiptFile: receipt, coverageFile: policy };
+}
+
+function arg(argv, name, fallback = null) {
+  const index = argv.indexOf(name);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const root = path.resolve(arg(argv, '--root', DEFAULT_ROOT));
+  const archiveFile = path.resolve(arg(argv, '--seed-archive', ''));
+  const seedTag = arg(argv, '--seed-tag');
+  const seedSha256 = arg(argv, '--seed-sha256');
+  const assetsDir = path.resolve(arg(argv, '--assets', ''));
+  const workspaceDir = path.resolve(arg(argv, '--workspace', ''));
+  const coverageFile = path.resolve(arg(argv, '--coverage', path.join(root, 'data', 'source-coverage.json')));
+  const candidateDir = path.resolve(arg(argv, '--candidate-out', path.join(root, 'dist', 'corpus-candidate')));
+  const receiptFile = path.resolve(arg(argv, '--receipt-out', path.join(root, 'dist', 'corpus-receipt.json')));
+  const builderSha = String(arg(argv, '--builder-sha', '')).toLowerCase();
+  const owner = arg(argv, '--owner', 'ruvnet');
+
+  assertBootstrapIdentity({ archiveFile, tag: seedTag, sha256: seedSha256, allowPinnedTag: process.argv.includes('--allow-pinned-seed-tag') });
+  if (fs.existsSync(assetsDir) && fs.readdirSync(assetsDir).length) fail(`bootstrap assets directory is not empty (${assetsDir})`);
+  fs.mkdirSync(path.dirname(assetsDir), { recursive: true });
+  const extractParent = fs.mkdtempSync(path.join(path.dirname(assetsDir), '.corpus-seed-extract-'));
+  await extractZip(archiveFile, extractParent);
+  normalizeExtractedCorpus({ extractedDir: extractParent, assetsDir });
+  const privateFence = path.join(root, 'kb', 'PRIVATE-STORES.json');
+  if (!fs.existsSync(privateFence)) fail(`canonical private-store fence missing (${privateFence})`);
+  fs.copyFileSync(privateFence, path.join(assetsDir, 'PRIVATE-STORES.json'), fs.constants.COPYFILE_EXCL);
+  fs.rmSync(extractParent, { recursive: true, force: true });
+  const coverageScript = path.join(root, 'scripts', 'source-coverage.mjs');
+  checked(defaultRun, process.execPath, [coverageScript, '--owner', owner, '--assets', assetsDir, '--write'], { stdio: 'inherit' });
+  const policy = readJson(coverageFile, 'source coverage policy');
+  const ledger = readJson(path.join(assetsDir, 'RVF-GENERATIONS.json'), 'bootstrap RVF generation ledger');
+  const plan = planReconciliation({ coverage: policy, ledger, assetsDir });
+  const reconciliation = executeReconciliation({ plan, assetsDir, workspaceDir, root });
+  const candidate = prepareCorpusCandidate({ root, assetsDir, owner, builderSha, candidateDir, receiptFile, coverageFile });
+  process.stdout.write(`${JSON.stringify({ ok: true, seedTag, seedSha256, plan, ...reconciliation, ...candidate }, null, 2)}\n`);
+  return 0;
+}
+
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/corpus-seed-publish.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Publish a corpus candidate once, under a tag derived from its exact archive digest.
+
+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 { verifyCorpusReceipt } from './corpus-candidate.mjs';
+
+function fail(message) {
+  throw new Error(`[corpus-seed-publish] ${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');
+}
+
+export function corpusSeedTag(receipt) {
+  if (!/^[a-f0-9]{64}$/.test(receipt?.archive?.sha256 || '')) fail('cannot derive tag without an archive sha256');
+  return `corpus-sha256-${receipt.archive.sha256}`;
+}
+
+function defaultRun(command, args, options) {
+  return spawnSync(command, args, { encoding: 'utf8', ...options });
+}
+
+export function publishCorpusSeed({
+  receiptFile,
+  bundleFile,
+  assetsDir,
+  policyFile,
+  repo,
+  run = defaultRun,
+}) {
+  const receiptPath = path.resolve(receiptFile || '');
+  const bundlePath = path.resolve(bundleFile || '');
+  if (!assetsDir || !policyFile) fail('publishing requires --assets and --policy for full receipt verification');
+  const receipt = verifyCorpusReceipt({
+    receiptFile: receiptPath,
+    bundleFile: bundlePath,
+    assetsDir,
+    policyFile,
+  });
+  if (!fs.existsSync(bundlePath)) fail(`bundle missing (${bundlePath})`);
+  const archiveSha256 = sha256File(bundlePath);
+  if (archiveSha256 !== receipt.archive.sha256) fail(`archive sha256=${archiveSha256}, receipt=${receipt.archive.sha256}`);
+  if (fs.statSync(bundlePath).size !== receipt.archive.bytes) fail('archive byte length differs from receipt');
+
+  const tag = corpusSeedTag(receipt);
+  const repoArgs = repo ? ['--repo', repo] : [];
+  const view = run('gh', ['release', 'view', tag, '--json', 'tagName', ...repoArgs], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (view.status === 0) fail(`release ${tag} already exists; refusing to overwrite immutable corpus seed`);
+  const viewError = String(view.stderr || view.stdout || '');
+  if (!/(not found|404|no release found)/i.test(viewError)) {
+    fail(`cannot prove ${tag} is absent (${viewError.trim() || `gh exited ${view.status}`})`);
+  }
+
+  // Publication stays behind the repository's one-publisher authority. This wrapper validates and
+  // seals the corpus inputs; scripts/release.mjs owns the protected GitHub mutation and its receipt.
+  const publish = run(process.execPath, [
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'release.mjs'),
+    '--corpus-seed',
+    '--corpus-tag', tag,
+    '--corpus-bundle', bundlePath,
+    '--corpus-receipt', receiptPath,
+    '--target', receipt.builderSourceSha,
+    ...(repo ? ['--repo', repo] : []),
+  ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (publish.status !== 0) fail(`protected corpus publication failed (${String(publish.stderr || publish.stdout || '').trim()})`);
+  return {
+    tag,
+    archiveSha256,
+    receiptSha256: sha256File(receiptPath),
+    draft: false,
+    prerelease: true,
+  };
+}
+
+function arg(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+async function main() {
+  const result = publishCorpusSeed({
+    receiptFile: arg('--receipt', 'dist/corpus-receipt.json'),
+    bundleFile: arg('--bundle', 'dist/ruvnet-brain.zip'),
+    assetsDir: arg('--assets'),
+    policyFile: arg('--policy'),
+    repo: arg('--repo'),
+  });
+  console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+}
+
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(error.message); process.exitCode = 1; });
+}