ruvnet-brain 4.0.90-dev → 4.3.1-dev

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

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// 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';
+const HEX_GIST = /^[a-f0-9]{20,64}$/;
+const HEX40 = /^[a-f0-9]{40}$/;
+const HEX64 = /^[a-f0-9]{64}$/;
+
+function fail(message) {
+  throw new Error(`[rebuild-gists-from-receipts] ${message}`);
+}
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+const jsonLine = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+
+function validDate(value) {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value) && Number.isFinite(Date.parse(value));
+}
+
+function validateFilename(filename, label) {
+  if (typeof filename !== 'string' || !filename || filename.includes('\0')
+    || filename.split(/[\\/]/).some((segment) => !segment || segment === '.' || segment === '..')) {
+    fail(`${label} has an unsafe or missing filename`);
+  }
+}
+
+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');
+  if (!source.gists || typeof source.gists !== 'object' || Array.isArray(source.gists)) {
+    fail('source receipt gists must be an object');
+  }
+  if (Object.keys(source.gists).length === 0) fail('source receipt has no gist receipts');
+
+  for (const [gistId, receipt] of Object.entries(source.gists)) {
+    const label = `gist ${gistId}`;
+    if (!HEX_GIST.test(gistId)) fail(`${label} id is malformed`);
+    if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) fail(`${label} receipt is malformed`);
+    if (receipt.complete !== true) fail(`${label} receipt is incomplete`);
+    if (!HEX40.test(String(receipt.versionSha || ''))) fail(`${label} versionSha is malformed`);
+    if (!validDate(receipt.updatedAt) || !validDate(receipt.ingestedAt)) fail(`${label} timestamps are malformed`);
+    if (!Array.isArray(receipt.files) || receipt.files.length === 0) fail(`${label} has no complete file inventory`);
+    const filenames = new Set();
+    for (const file of receipt.files) {
+      validateFilename(file?.filename, label);
+      if (filenames.has(file.filename)) fail(`${label} has duplicate filename ${file.filename}`);
+      filenames.add(file.filename);
+      if (file.included === true) {
+        if (!HEX64.test(String(file.sha256 || '')) || !Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+          fail(`${label}/${file.filename} has malformed included-file identity`);
+        }
+      } else if (file.included !== false || typeof file.reason !== 'string' || !file.reason
+        || !(file.size === null || (Number.isSafeInteger(file.size) && file.size >= 0))) {
+        fail(`${label}/${file.filename} has malformed exclusion evidence`);
+      }
+    }
+    const expectedDigest = sha256(JSON.stringify(receipt.files));
+    if (!HEX64.test(String(receipt.contentDigest || '')) || receipt.contentDigest !== expectedDigest) {
+      fail(`${label} contentDigest does not match its file inventory`);
+    }
+  }
+  return source;
+}
+
+export function rawUrlFor({ owner, gistId, versionSha, filename }) {
+  if (!/^[A-Za-z0-9-]{1,39}$/.test(String(owner || '')) || !HEX_GIST.test(String(gistId || ''))
+    || !HEX40.test(String(versionSha || ''))) fail('cannot construct raw URL from malformed source identity');
+  validateFilename(filename, `gist ${gistId}`);
+  const encodedFile = filename.split('/').map(encodeURIComponent).join('/');
+  return `https://gist.githubusercontent.com/${owner}/${gistId}/raw/${versionSha}/${encodedFile}`;
+}
+
+export function paragraphChunks(text, size = 3200) {
+  if (typeof text !== 'string') fail('passage content must be text');
+  if (!Number.isSafeInteger(size) || size < 1) fail('chunk size must be a positive integer');
+  const out = [];
+  let buffer = '';
+  for (const paragraph of text.split(/\n\n+/)) {
+    if (buffer && buffer.length + paragraph.length + 2 > size) {
+      out.push(buffer);
+      buffer = '';
+    }
+    buffer = buffer ? `${buffer}\n\n${paragraph}` : paragraph;
+  }
+  if (buffer.trim()) out.push(buffer);
+  return out;
+}
+
+export function provenanceBanner({ owner, gistId, filename, updatedAt }) {
+  return `SOURCE: GitHub gist by @${owner} — "${filename.replace(/\s+/g, ' ').trim().slice(0, 160)}"\n`
+    + `GIST STATUS: rUv's own notes / release announcement — may describe PROPOSED or UNRELEASED work.\n`
+    + `Treat as intent, not as confirmed shipped behavior: verify against repo source before asserting.\n`
+    + `updated: ${updatedAt.slice(0, 10)} · https://gist.github.com/${owner}/${gistId}\n\n`;
+}
+
+async function mapBounded(items, concurrency, operation) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await operation(items[index]);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+  return results;
+}
+
+export async function reconstructGists(source, { fetchFn = globalThis.fetch, concurrency = 6 } = {}) {
+  validateSourceReceipts(source);
+  if (typeof fetchFn !== 'function') fail('fetch implementation is unavailable');
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 32) {
+    fail('concurrency must be an integer from 1 through 32');
+  }
+
+  const jobs = [];
+  for (const [gistId, receipt] of Object.entries(source.gists)) {
+    for (const file of receipt.files) {
+      if (file.included) jobs.push({ gistId, receipt, file });
+    }
+  }
+  const bodies = await mapBounded(jobs, concurrency, async ({ gistId, receipt, file }) => {
+    const url = rawUrlFor({ owner: source.owner, gistId, versionSha: receipt.versionSha, filename: file.filename });
+    const response = await fetchFn(url, {
+      headers: { accept: 'text/plain', 'user-agent': 'ruvnet-brain-gist-receipt-rebuild' },
+    });
+    if (!response?.ok) fail(`${gistId}/${file.filename} raw fetch failed: HTTP ${response?.status ?? 'unknown'}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length !== file.bytes) fail(`${gistId}/${file.filename} byte count ${bytes.length} differs from receipt ${file.bytes}`);
+    const digest = sha256(bytes);
+    if (digest !== file.sha256) fail(`${gistId}/${file.filename} sha256 ${digest} differs from receipt ${file.sha256}`);
+    let body;
+    try {
+      body = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch {
+      fail(`${gistId}/${file.filename} is not valid UTF-8 text`);
+    }
+    return body;
+  });
+
+  const passages = [];
+  const entries = {};
+  let bodyIndex = 0;
+  let id = 0;
+  for (const [gistId, receipt] of Object.entries(source.gists)) {
+    for (const file of receipt.files) {
+      if (!file.included) continue;
+      const body = bodies[bodyIndex++];
+      const chunks = paragraphChunks(body);
+      const title = file.filename.replace(/\s+/g, ' ').trim().slice(0, 180) || file.filename;
+      const banner = provenanceBanner({ owner: source.owner, gistId, filename: file.filename, updatedAt: receipt.updatedAt });
+      for (const [chunkIndex, chunk] of chunks.entries()) {
+        const passageId = String(id++);
+        const passagePath = `${gistId.slice(0, 8)}/${file.filename}${chunks.length > 1 ? `#${chunkIndex}` : ''}`;
+        const text = banner + chunk;
+        passages.push({ id: passageId, text, path: passagePath, title });
+        entries[passageId] = { path: passagePath, kind: 'doc', title, chunk: chunkIndex, preview: text.slice(0, 200) };
+      }
+    }
+  }
+  const passageBody = passages.map(jsonLine).join('\n') + '\n';
+  const meta = {
+    model: NAME,
+    dimensions: 0,
+    metric: 'cosine',
+    name: NAME,
+    generated: source.generated,
+    repo: `gists/${source.owner}`,
+    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 === 3
+      ? sealGistReceiptSet({ ...source, passagesSha256 })
+      : { ...source, schemaVersion: 2, passagesSha256, gists: source.gists },
+  };
+}
+
+export function writeReconstruction(result, { outDir }) {
+  const output = path.resolve(outDir || '');
+  if (!result?.passageBody || !result.meta || !result.sources) fail('complete reconstruction result is required');
+  fs.mkdirSync(output, { recursive: true });
+  const files = {
+    passagesFile: path.join(output, `${NAME}.passages.jsonl`),
+    metaFile: path.join(output, `${NAME}.meta.json`),
+    sourcesFile: path.join(output, `${NAME}.sources.json`),
+  };
+  const contents = new Map([
+    [files.passagesFile, result.passageBody],
+    [files.metaFile, `${JSON.stringify(result.meta, null, 2)}\n`],
+    [files.sourcesFile, `${JSON.stringify(result.sources, null, 2)}\n`],
+  ]);
+  const staged = [];
+  try {
+    for (const [file, content] of contents) {
+      const temporary = `${file}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+      fs.writeFileSync(temporary, content, { flag: 'wx' });
+      staged.push([temporary, file]);
+    }
+    for (const [temporary, file] of staged) fs.renameSync(temporary, file);
+  } finally {
+    for (const [temporary] of staged) fs.rmSync(temporary, { force: true });
+  }
+  return files;
+}
+
+function option(argv, name, fallback) {
+  const index = argv.indexOf(name);
+  return index >= 0 && argv[index + 1] && !argv[index + 1].startsWith('--') ? argv[index + 1] : fallback;
+}
+
+/**
+ * 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', resolveSourcesFile({ repoRoot, env, home })));
+  const outDir = path.resolve(option(argv, '--out-dir', path.dirname(sourcesFile)));
+  const concurrency = Number(option(argv, '--concurrency', '6'));
+  let source;
+  try {
+    source = JSON.parse(fs.readFileSync(sourcesFile, 'utf8'));
+  } catch (error) {
+    fail(`cannot read source receipts ${sourcesFile}: ${error.message}`);
+  }
+  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;
+}
+
+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;
+  });
+}