ruvnet-brain 4.0.90-dev → 4.3.1-dev

package/scripts/self-update.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// self-update.mjs — nightly evergreen driver.
+// self-update.mjs — author-side incremental candidate builder.
 // Compares each in-scope repo's live HEAD against the stamped manifest, then (re)builds the segments
 // that changed and re-stamps. Dry-run by default; pass --apply to actually (re)build.
 //
@@ -12,14 +12,16 @@
 // candidate bytes, but only the protected release workflow may publish them after release-proof
 // seals the exact clean SHA and packed-artifact digest.
 //
-// Designed to be invoked by deploy/com.ruvnet.brain-nightly.plist (LaunchAgent — NOT auto-installed).
+// Author-side candidate builder. It is never scheduled against a developer checkout. The retired
+// com.ruvnet.brain-nightly LaunchAgent did exactly that and accumulated generated changes beside
+// live work. Run --apply only from a clean linked worktree outside the primary checkout.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { FULL_HINTS, KEEP_DIRS } from './full-hints.mjs';
 import { withSubmoduleSymlinksDetached } from './git-clone-refresh.mjs';
+import { assertIsolatedMutationWorktree } from './worktree-integrity.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -57,45 +59,18 @@ if (has('--publish')) {
   console.error('[release-authority] Use the protected release workflow after release-proof seals the exact clean SHA and packed-artifact digest.');
   process.exit(2);
 }
-// --publish's whole job is to end this run with `git commit` + `git push origin main` (see the
-// PUBLISH block far below) — and those two commands operate on whatever branch is CURRENTLY
-// CHECKED OUT in this working tree, not necessarily main. Real failure (2026-07-19): the nightly
-// fired at 03:15 while a developer had feat/meta-proxy-passthrough checked out, and commit 4a10833
-// "Nightly brain refresh v3.4.21-dev" landed silently on THAT branch — a version-bump commit no
-// release will ever be cut from, stranded on top of someone's unrelated in-progress work.
-// Guard here, before ANY of the (hours-long, CPU-bound) rebuild work below even starts, and before
-// the GitHub Release / npm publish steps run — checking branch only at commit-time would still
-// burn a full night's rebuild, or worse, leave a Release cut with no matching version-bump commit
-// to go with it. We deliberately do NOT `git checkout main` to self-correct: this machine is
-// routinely mid-task on a feature branch at 03:15 (that is exactly how this bug was found), and
-// switching branches out from under someone's uncommitted work is precisely the "clever and
-// destructive" move this repo has already been burned by once (see the -readonly/timeout lesson in
-// CLAUDE.md Rule 19). An aborted nightly that logs clearly and reruns tomorrow costs nothing; a
-// checkout that clobbers a developer's working tree cannot be undone.
-// ── THE BRANCH GUARD IS GONE, AND THAT IS THE FIX (2026-07-24) ──────────────────────────────────
-//
-// It used to FATAL here when ROOT was not on main. That guard was CORRECT for what it knew: these
-// git commands act on whatever branch is checked out, and on 2026-07-19 that stranded commit 4a10833
-// on feat/meta-proxy-passthrough. Refusing beat clobbering a developer's working tree.
-//
-// But refusing had a cost nobody was watching. This file is the ONLY thing that cuts GitHub Releases
-// (`release.mjs --publish` does npm and contains zero `gh release` calls). So on 2026-07-23 the
-// nightly hit this guard — the repo was on branch 4.0 — aborted correctly, and the release channel
-// froze at v3.9.18-dev while npm advanced to 3.9.50. Thirty-two versions of drift produced by a guard
-// working exactly as designed, invisible because the channel verifier only checked the bundle was
-// REACHABLE, never that it was CURRENT.
-//
-// The dilemma was false. It only existed because the version commit ran in ROOT. It now runs in a
-// worktree pinned to origin/main (see the PUBLISH block), so the developer's tree is never touched
-// AND the release is never blocked by what they have checked out. Neither horn, rather than a better
-// choice between them.
-//
-// Nothing replaces this check because nothing needs to: ROOT's branch is now irrelevant to publishing.
-// If the worktree cannot be prepared, THAT fails loudly and refuses to fall back to committing in
-// ROOT — the guarantee this guard existed to provide, kept, without the outage it caused.
+if (APPLY) {
+  try { assertIsolatedMutationWorktree(ROOT, 'self-update --apply'); }
+  catch (error) { console.error(error?.message || String(error)); process.exit(2); }
+}
+// Historical note: this script once published and committed from whichever branch happened to be
+// checked out. Publication authority has since moved to protected-release.yml and --publish is
+// refused above. The remaining rebuild still writes generated candidate source, so the stronger
+// boundary is now structural: assertIsolatedMutationWorktree refuses primary, nested, non-linked,
+// and dirty worktrees before any expensive or mutating step begins.
 // --fresh-window <days>: LIVE-scan the org(s) and take every non-fork/non-archived repo pushed within
-// N days, bypassing the static registry.tiers.json AND the nightly T3 skip. This is THE fix for
-// "new repos rUv shipped never got ingested" — a brand-new repo is discovered and built the same night
+// N days, bypassing the static registry.tiers.json AND the default T3 skip. This is THE fix for
+// "new repos rUv shipped never got ingested" — a brand-new repo is discovered and built in the same run
 // it appears, but only within the rolling window, so the old "days of compute for all 173" risk that the
 // tier gate guarded against still cannot happen. Absent this flag, scoping is byte-for-byte unchanged.
 const FRESH_WINDOW = arg('--fresh-window', null);
@@ -158,7 +133,7 @@ if (FRESH_WINDOW) {
     if (TIER && t !== TIER) continue;
     for (const r of tiers.tiers[t].repos) {
       if (ONLY && r.name !== ONLY) continue;
-      if (t === 'T3' && !ONLY) continue;            // T3 is deep-walked on demand, not nightly
+      if (t === 'T3' && !ONLY) continue;            // T3 is deep-walked only when named explicitly
       inScope.push({ ...r, tier: t });
     }
   }
@@ -205,9 +180,9 @@ if (typeof orgFailures !== 'undefined' && orgFailures > 0 && inScope.length ===
 
 console.log(`self-update ${APPLY ? '(APPLY)' : '(dry-run)'} — ${plan.length} repos in scope\n`);
 for (const p of plan) console.log(`  ${p.action.padEnd(20)} ${p.tier} ${p.name.padEnd(24)} built:${p.built}  live:${p.live}`);
-// SAFE NIGHTLY SCOPE: by default only REBUILD already-built repos whose upstream changed (keeps the
+// SAFE DEFAULT SCOPE: only REBUILD already-built repos whose upstream changed (keeps the
 // shipped bundle current). Building brand-new repos is a supervised, multi-hour scaling effort, NOT an
-// unattended nightly job — gate it behind --include-new so the cron can't silently try to deep-walk 40+
+// implicit default — gate it behind --include-new so an ordinary author run cannot silently deep-walk 40+
 // repos (days of compute) on its first run.
 // Fresh-window mode exists precisely to discover + build brand-new repos, so default INCLUDE_NEW on
 // there (still bounded to the N-day set). Static-tier mode keeps the original opt-in gate untouched.

package/scripts/source-coverage.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readRvfGenerations, sha256File } from './rvf-generation.mjs';
+import { canonicalJson, coverageGenerationFor, digest, validateGistAggregateReceipt } from './coverage-integrity.mjs';
+
+export { canonicalJson, digest } from './coverage-integrity.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REPO_QUERY = `query($login:String!,$cursor:String){
+  user(login:$login){
+    publicRepositories:repositories(privacy:PUBLIC){totalCount}
+    repositories(first:100,after:$cursor,privacy:PUBLIC,ownerAffiliations:OWNER,orderBy:{field:NAME,direction:ASC}){
+      pageInfo{hasNextPage endCursor}
+      nodes{databaseId name url description homepageUrl isFork isArchived isDisabled diskUsage updatedAt pushedAt
+        defaultBranchRef{name target{... on Commit{oid committedDate}}}}
+    }
+  }
+}`;
+
+function runGh(args) {
+  const result = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 128 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`gh ${args.join(' ')} failed: ${(result.stderr || '').trim()}`);
+  return result.stdout;
+}
+
+export function observeRepositories(owner, { gh = runGh } = {}) {
+  const rows = [];
+  const pages = [];
+  let cursor = '';
+  do {
+    const raw = gh(['api', 'graphql', '-f', `query=${REPO_QUERY}`, '-F', `login=${owner}`,
+      ...(cursor ? ['-F', `cursor=${cursor}`] : [])]);
+    const body = JSON.parse(raw);
+    const connection = body?.data?.user?.repositories;
+    if (!connection) throw new Error('GitHub repository enumeration returned no repository connection');
+    pages.push({ cursor: cursor || null, responseDigest: digest(body), count: connection.nodes.length,
+      endCursor: connection.pageInfo.endCursor, hasNextPage: connection.pageInfo.hasNextPage });
+    rows.push(...connection.nodes);
+    cursor = connection.pageInfo.hasNextPage ? connection.pageInfo.endCursor : '';
+  } while (cursor);
+  const expected = rows.length ? Number(JSON.parse(gh(['api', `users/${owner}`])).public_repos) : 0;
+  if (rows.length !== expected) throw new Error(`repository enumeration incomplete: ${rows.length}/${expected}`);
+  return { rows, expected, pages };
+}
+
+export function observeExternalRepositories(sources, { gh = runGh } = {}) {
+  const rows = [];
+  const pages = [];
+  for (const source of sources) {
+    if (!source?.store || !/^[^/]+\/[^/]+$/.test(source?.repository || '')) {
+      throw new Error('external source requires a store and owner/repository');
+    }
+    const repo = JSON.parse(gh(['api', `repos/${source.repository}`]));
+    const commit = repo.default_branch
+      ? JSON.parse(gh(['api', `repos/${source.repository}/commits/${repo.default_branch}`]))
+      : null;
+    const row = {
+      databaseId: repo.id, name: repo.name, fullName: repo.full_name, storeName: source.store,
+      url: repo.html_url, description: repo.description || null, homepageUrl: repo.homepage || null,
+      isFork: false, upstreamIsFork: repo.fork,
+      isArchived: repo.archived, isDisabled: repo.disabled,
+      diskUsage: repo.size, updatedAt: repo.updated_at, pushedAt: repo.pushed_at,
+      defaultBranchRef: commit ? { name: repo.default_branch, target: {
+        oid: commit.sha, committedDate: commit.commit?.committer?.date || commit.commit?.author?.date || null,
+      } } : null,
+    };
+    rows.push(row);
+    pages.push({ repository: source.repository, responseDigest: digest({ repo, commit }), count: 1, terminal: true });
+  }
+  return { rows, expected: rows.length, pages };
+}
+
+export function observeSourceUniverse({
+  owner = 'ruvnet',
+  externalSources = [],
+  gh = runGh,
+  observedAt = new Date().toISOString(),
+} = {}) {
+  const primary = observeRepositories(owner, { gh });
+  const external = observeExternalRepositories(externalSources, { gh });
+  const repositoryRows = canonicalRepositoryRows([...primary.rows, ...external.rows]);
+  const repositories = sourceSetObservation(repositoryRows, primary.expected + external.expected);
+  const repositoryKeys = new Set();
+  const storeKeys = new Set();
+  for (const repo of repositories.rows) {
+    const repositoryKey = String(repo.fullName || `${owner}/${repo.name}`).toLowerCase();
+    const storeKey = storeName(repo.storeName || repo.name);
+    if (repositoryKeys.has(repositoryKey)) throw new Error(`source observation has duplicate repository: ${repositoryKey}`);
+    if (storeKeys.has(storeKey)) throw new Error(`source observation has colliding store name: ${storeKey}`);
+    repositoryKeys.add(repositoryKey);
+    storeKeys.add(storeKey);
+  }
+  const observedGists = observeGists(owner, { gh });
+  const gists = sourceSetObservation(canonicalGistRows(observedGists.rows), observedGists.expected);
+  return canonicalSourceObservation({
+    schemaVersion: 1,
+    kind: 'ruvnet-brain-source-observation',
+    owner,
+    observedAt,
+    repositories,
+    gists,
+  });
+}
+
+export function sourceObservationDigest(observation) {
+  const stable = canonicalSourceObservation(observation, { seal: false });
+  return digest({ schemaVersion: stable.schemaVersion, kind: stable.kind,
+    owner: stable.owner, repositories: stable.repositories, gists: stable.gists });
+}
+
+function sourceSetObservation(rows, expected) {
+  return { rows, expected, pages: [{ index: 1, responseDigest: digest(rows), count: rows.length, terminal: true }] };
+}
+
+export function canonicalRepositoryRows(rows = []) {
+  return rows.map((repo) => ({
+    databaseId: repo?.databaseId,
+    name: repo?.name,
+    ...(repo?.fullName === undefined ? {} : { fullName: repo.fullName }),
+    ...(repo?.storeName === undefined ? {} : { storeName: repo.storeName }),
+    url: repo?.url,
+    description: repo?.description ?? null,
+    homepageUrl: repo?.homepageUrl ?? null,
+    isFork: repo?.isFork === true,
+    ...(repo?.upstreamIsFork === undefined ? {} : { upstreamIsFork: repo.upstreamIsFork === true }),
+    isArchived: repo?.isArchived === true,
+    isDisabled: repo?.isDisabled === true,
+    diskUsage: repo?.diskUsage,
+    updatedAt: repo?.updatedAt ?? null,
+    pushedAt: repo?.pushedAt ?? null,
+    defaultBranchRef: repo?.defaultBranchRef ? {
+      name: repo.defaultBranchRef.name,
+      target: repo.defaultBranchRef.target ? {
+        oid: repo.defaultBranchRef.target.oid,
+        committedDate: repo.defaultBranchRef.target.committedDate ?? null,
+      } : null,
+    } : null,
+  })).sort((a, b) => {
+    const identity = (row) => String(row.fullName || row.name || '').toLowerCase();
+    return identity(a).localeCompare(identity(b))
+      || String(a.storeName || '').toLowerCase().localeCompare(String(b.storeName || '').toLowerCase())
+      || Number(a.databaseId || 0) - Number(b.databaseId || 0);
+  });
+}
+
+export function canonicalGistRows(rows = []) {
+  return rows.map((gist) => ({
+    id: gist?.id,
+    updated_at: gist?.updated_at ?? null,
+    html_url: gist?.html_url,
+    files: Object.fromEntries(Object.entries(gist?.files || {}).sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, file]) => [key, {
+        filename: file?.filename,
+        raw_url: file?.raw_url,
+        size: file?.size,
+        type: file?.type,
+        language: file?.language ?? null,
+      }])),
+  })).sort((a, b) => String(a.id || '').localeCompare(String(b.id || '')));
+}
+
+export function canonicalSourceObservation(observation, { seal = true } = {}) {
+  const repositories = sourceSetObservation(canonicalRepositoryRows(observation?.repositories?.rows),
+    observation?.repositories?.expected);
+  const gists = sourceSetObservation(canonicalGistRows(observation?.gists?.rows), observation?.gists?.expected);
+  const stable = {
+    schemaVersion: observation?.schemaVersion,
+    kind: observation?.kind,
+    owner: observation?.owner,
+    observedAt: observation?.observedAt,
+    repositories,
+    gists,
+  };
+  if (!seal) return stable;
+  return { ...stable, observationSha256: sourceObservationDigest(stable) };
+}
+
+export function gistVersion(gist) {
+  const versions = Object.values(gist.files || {}).flatMap((file) => {
+    const match = String(file.raw_url || '').match(/\/raw\/([0-9a-f]{7,64})\//i);
+    return match ? [match[1]] : [];
+  });
+  return versions.length && new Set(versions).size === 1 ? versions[0] : null;
+}
+
+export function observeGists(owner, { gh = runGh } = {}) {
+  const raw = gh(['api', `users/${owner}/gists?per_page=100`, '--paginate', '--slurp']);
+  const parsed = JSON.parse(raw);
+  const pages = Array.isArray(parsed[0]) ? parsed : [parsed];
+  const rows = pages.flat().filter((gist) => gist?.id);
+  const expected = Number(JSON.parse(gh(['api', `users/${owner}`])).public_gists);
+  if (rows.length !== expected) throw new Error(`gist enumeration incomplete: ${rows.length}/${expected}`);
+  return {
+    rows,
+    expected,
+    pages: pages.map((page, index) => ({ index: index + 1, responseDigest: digest(page), count: page.length,
+      terminal: index === pages.length - 1 })),
+  };
+}
+
+function storeName(name) { return String(name).toLowerCase(); }
+
+export function classifyRepository(repo, evidence, exclusion = null) {
+  const activeExclusion = exclusion && String(exclusion.pushedAt || '') !== ''
+    && String(exclusion.pushedAt) === String(repo.pushedAt || '');
+  const disposition = activeExclusion ? 'excluded-no-corpus' : repo.isFork ? 'fork' : repo.isArchived ? 'archived' :
+    repo.isDisabled ? 'disabled' : !repo.defaultBranchRef ? 'empty' : 'eligible';
+  const upstreamSha = repo.defaultBranchRef?.target?.oid || null;
+  const reasons = [];
+  let status = 'CURRENT';
+  if (disposition !== 'eligible') {
+    status = 'INELIGIBLE';
+    if (activeExclusion && exclusion?.reason) reasons.push(exclusion.reason);
+  }
+  else if (!evidence.rvfPresent) { status = 'MISSING'; reasons.push('canonical RVF is absent'); }
+  else if (!evidence.receipt?.sourceCommit) { status = 'UNVERIFIED'; reasons.push('RVF receipt has no sourceCommit'); }
+  else if (evidence.receipt.sourceCommit !== upstreamSha) { status = 'STALE'; reasons.push('receipt sourceCommit differs from upstream HEAD'); }
+  else if (!evidence.bytesVerified) { status = 'FAILED'; reasons.push('RVF bytes do not match receipt'); }
+  else if (!evidence.passagesPresent) { status = 'FAILED'; reasons.push('passage inventory is absent'); }
+  return {
+    key: repo.fullName ? `repo:${repo.fullName.toLowerCase()}` : `repo:${repo.databaseId}`,
+    kind: 'repository',
+    name: repo.name,
+    url: repo.url,
+    routing: { description: repo.description || null, homepageUrl: repo.homepageUrl || null,
+      capabilityCardPresent: evidence.cardPresent === true },
+    disposition,
+    upstream: { sha: upstreamSha, committedAt: repo.defaultBranchRef?.target?.committedDate || null,
+      pushedAt: repo.pushedAt, updatedAt: repo.updatedAt },
+    artifact: { store: storeName(repo.storeName || repo.name), sourceCommit: evidence.receipt?.sourceCommit || null,
+      ingestedAt: evidence.receipt?.builtUtc || null, rvfSha256: evidence.receipt?.sha256 || null,
+      bytesVerified: evidence.bytesVerified, passagesPresent: evidence.passagesPresent,
+      cardPresent: evidence.cardPresent },
+    status,
+    reasons,
+  };
+}
+
+export function classifyGist(gist, evidence) {
+  const source = evidence.sources?.gists?.[gist.id] || null;
+  const ingestedAt = source?.ingestedAt || evidence.cache?.[gist.id] || null;
+  // The list API does not expose gist history.version. A just-fetched individual source receipt is
+  // still the authoritative version when the live list's updated_at is unchanged; otherwise the
+  // list proves drift and the row is stale until the individual gist is refreshed.
+  const version = source?.updatedAt === gist.updated_at ? source.versionSha : gistVersion(gist);
+  const currentByDate = source?.updatedAt === gist.updated_at || evidence.cache?.[gist.id] === gist.updated_at;
+  let status = 'CURRENT';
+  const reasons = [];
+  if (!evidence.rvfPresent) { status = 'MISSING'; reasons.push('ruv-gists RVF is absent'); }
+  else if (!evidence.receipt || !source || !version) { status = 'UNVERIFIED'; reasons.push('per-gist source receipt is absent'); }
+  else if (!evidence.bytesVerified) { status = 'FAILED'; reasons.push('ruv-gists RVF bytes do not match the generation receipt'); }
+  else if (!evidence.passagesBound) { status = 'FAILED'; reasons.push('gist passages do not match the source receipt'); }
+  else if (!source.complete) { status = 'FAILED'; reasons.push('per-gist source receipt is incomplete'); }
+  else if (source.versionSha !== version || !currentByDate) { status = 'STALE'; reasons.push('ingested gist identity differs from upstream'); }
+  const filenames = Object.values(gist.files || {}).map((file) => file?.filename).filter(Boolean).sort();
+  return {
+    key: `gist:${gist.id}`,
+    kind: 'gist',
+    name: Object.values(gist.files || {})[0]?.filename || gist.id,
+    url: gist.html_url,
+    disposition: 'eligible',
+    upstream: { sha: version, updatedAt: gist.updated_at, fileCount: filenames.length, files: filenames },
+    artifact: { store: 'ruv-gists', sourceCommit: source?.versionSha || null, ingestedAt: source?.ingestedAt || ingestedAt,
+      contentDigest: source?.contentDigest || null, fileCount: source?.files?.length || null,
+      rvfSha256: evidence.receipt?.sha256 || null, bytesVerified: evidence.bytesVerified },
+    status,
+    reasons,
+  };
+}
+
+function artifactEvidence(kbDir, ledger, cardStores, name) {
+  const store = storeName(name);
+  const receipt = Object.entries(ledger.stores).find(([key]) => key.toLowerCase() === store)?.[1] || null;
+  const rvfFile = receipt?.file || `${store}.big.rvf`;
+  const rvfPath = path.join(kbDir, rvfFile);
+  const rvfPresent = fs.existsSync(rvfPath) && fs.lstatSync(rvfPath).isFile();
+  return {
+    receipt,
+    rvfPresent,
+    bytesVerified: Boolean(rvfPresent && receipt?.sha256 && sha256File(rvfPath) === receipt.sha256),
+    passagesPresent: fs.existsSync(path.join(kbDir, `${store}.passages.jsonl`))
+      && fs.statSync(path.join(kbDir, `${store}.passages.jsonl`)).size > 0,
+    cardPresent: cardStores.has(store),
+  };
+}
+
+export function renderMarkdown(coverage) {
+  const counts = coverage.totals.byStatus;
+  const lines = [
+    '# RuvNet Brain source coverage', '',
+    `Generated: ${coverage.observedAt}  `,
+    `Coverage generation: \`${coverage.coverageGeneration}\`  `,
+    `Repositories: ${coverage.totals.repositories} · Gists: ${coverage.totals.gists} · ` +
+      Object.entries(counts).sort().map(([state, count]) => `${state} ${count}`).join(' · '), '',
+    '> `CURRENT` is artifact-bound. Clone state and timestamps alone never establish freshness.', '',
+    '## Repositories', '',
+    '| Repository | Upstream updated | Upstream SHA | Ingested | Ingested SHA | State | Reason |',
+    '|---|---:|---|---:|---|---|---|',
+  ];
+  for (const row of coverage.rows.filter((entry) => entry.kind === 'repository')) {
+    lines.push(`| [${row.name}](${row.url}) | ${row.upstream.committedAt || row.upstream.updatedAt || '—'} | ${row.upstream.sha || '—'} | ${row.artifact.ingestedAt || '—'} | ${row.artifact.sourceCommit || '—'} | ${row.status} | ${row.reasons.join('; ') || row.disposition} |`);
+  }
+  lines.push('', '## Public gists', '',
+    '| Gist | Upstream updated | Version SHA | Ingested update | State | Reason |',
+    '|---|---:|---|---:|---|---|');
+  for (const row of coverage.rows.filter((entry) => entry.kind === 'gist')) {
+    lines.push(`| [${row.name}](${row.url}) | ${row.upstream.updatedAt || '—'} | ${row.upstream.sha || '—'} | ${row.artifact.ingestedAt || '—'} | ${row.status} | ${row.reasons.join('; ') || '—'} |`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function sealCoverage({ owner, repositories, gists, rows, generatorSourceSha, snapshotRoot, observedAt,
+  sourceObservationSha256 = null,
+  policyDispositionDigests = [], exemptionDigests = [] }) {
+  const enumerationReceipt = {
+    schemaVersion: 1, owner, observedAt, requestParameters: { repositoryPageSize: 100, gistPageSize: 100 },
+    repositories: { expected: repositories.expected, pages: repositories.pages },
+    gists: { expected: gists.expected, pages: gists.pages },
+    duplicateKeys: rows.length - new Set(rows.map((row) => row.key)).size,
+    terminal: true,
+  };
+  const orderedRows = [...rows].sort((a, b) => a.key.localeCompare(b.key));
+  const byStatus = Object.fromEntries([...new Set(orderedRows.map((row) => row.status))].sort()
+    .map((status) => [status, orderedRows.filter((row) => row.status === status).length]));
+  return { schemaVersion: 1, kind: 'ruvnet-brain-corpus-coverage', owner, observedAt, generatorSourceSha,
+    sourceObservationSha256, snapshotRoot,
+    policy: { policyDispositionDigests, exemptionDigests },
+    coverageGeneration: coverageGenerationFor({ generatorSourceSha, snapshotRoot, sourceObservationSha256, rows: orderedRows,
+      enumerationReceipt, policyDispositionDigests, exemptionDigests }), enumerationReceipt, rows: orderedRows,
+    totals: { repositories: repositories.expected, gists: gists.expected, rows: orderedRows.length, byStatus } };
+}
+
+export function buildCoverage({ owner = 'ruvnet', kbDir = path.join(ROOT, 'kb'), policyDir = kbDir,
+  observation = null, gh = runGh, now = () => new Date().toISOString() } = {}) {
+  const externalPath = path.join(policyDir, 'external-sources.json');
+  const externalPolicy = fs.existsSync(externalPath) ? JSON.parse(fs.readFileSync(externalPath, 'utf8')) : { sources: [] };
+  if (!Array.isArray(externalPolicy.sources)) throw new Error('external-sources.json has no sources array');
+  const suppliedObservation = observation || observeSourceUniverse({
+    owner, externalSources: externalPolicy.sources, gh, observedAt: now(),
+  });
+  if (suppliedObservation?.kind !== 'ruvnet-brain-source-observation'
+      || suppliedObservation.owner !== owner
+      || suppliedObservation.observationSha256 !== sourceObservationDigest(suppliedObservation)) {
+    throw new Error('source observation identity is missing or invalid');
+  }
+  const sourceObservation = canonicalSourceObservation(suppliedObservation);
+  const repositories = sourceObservation.repositories;
+  const gists = sourceObservation.gists;
+  const ledger = readRvfGenerations(kbDir);
+  const cards = fs.readFileSync(path.join(kbDir, 'capability-cards.md'), 'utf8');
+  const cardStores = new Set([...cards.matchAll(/^##\s+(.+?)\s*$/gm)].map((match) => storeName(match[1])));
+  const gistCachePath = path.join(kbDir, '.ruv-gists.cache.json');
+  const gistCache = fs.existsSync(gistCachePath) ? JSON.parse(fs.readFileSync(gistCachePath, 'utf8')) : {};
+  const gistSourcesPath = path.join(kbDir, 'ruv-gists.sources.json');
+  const gistSources = fs.existsSync(gistSourcesPath) ? JSON.parse(fs.readFileSync(gistSourcesPath, 'utf8')) : null;
+  const exclusionsPath = path.join(policyDir, 'no-corpus-repos.json');
+  const exclusions = fs.existsSync(exclusionsPath) ? JSON.parse(fs.readFileSync(exclusionsPath, 'utf8')) : {};
+  const rows = repositories.rows.map((repo) => {
+    const store = storeName(repo.storeName || repo.name);
+    return classifyRepository(repo, artifactEvidence(kbDir, ledger, cardStores, store), exclusions[store] || null);
+  });
+  const gistEvidence = { ...artifactEvidence(kbDir, ledger, cardStores, 'ruv-gists'), cache: gistCache, sources: gistSources };
+  try {
+    validateGistAggregateReceipt({ receipt: gistSources,
+      passagesFile: path.join(kbDir, 'ruv-gists.passages.jsonl'),
+      expectedIds: gists.rows.map(({ id }) => id),
+      sourceObservationSha256: sourceObservation.observationSha256 });
+    gistEvidence.passagesBound = true;
+  } catch {
+    gistEvidence.passagesBound = false;
+  }
+  rows.push(...gists.rows.map((gist) => classifyGist(gist, gistEvidence)));
+  const generatorSourceSha = sha256File(fileURLToPath(import.meta.url));
+  const snapshotRoot = digest({ stores: ledger.stores, files: rows.filter((row) => row.kind === 'repository')
+    .map((row) => ({ store: row.artifact.store, sha256: row.artifact.rvfSha256 })) });
+  return sealCoverage({ owner, repositories, gists, rows, generatorSourceSha, snapshotRoot,
+    observedAt: sourceObservation.observedAt, sourceObservationSha256: sourceObservation.observationSha256,
+    policyDispositionDigests: fs.existsSync(externalPath) ? [sha256File(externalPath)] : [],
+    exemptionDigests: fs.existsSync(exclusionsPath) ? [sha256File(exclusionsPath)] : [] });
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const ownerIndex = argv.indexOf('--owner');
+  const owner = ownerIndex >= 0 ? argv[ownerIndex + 1] : 'ruvnet';
+  const assetsIndex = argv.indexOf('--assets');
+  const kbDir = path.resolve(assetsIndex >= 0 ? argv[assetsIndex + 1] : path.join(ROOT, 'kb'));
+  const jsonPath = path.join(ROOT, 'data', 'source-coverage.json');
+  const markdownPath = path.join(ROOT, 'docs', 'RUVNET-COVERAGE.md');
+  const recorded = argv.includes('--check') && fs.existsSync(jsonPath)
+    ? JSON.parse(fs.readFileSync(jsonPath, 'utf8')) : null;
+  const coverage = buildCoverage({ owner, kbDir,
+    now: recorded?.observedAt ? () => recorded.observedAt : () => new Date().toISOString() });
+  const json = `${JSON.stringify(coverage, null, 2)}\n`;
+  const markdown = renderMarkdown(coverage);
+  if (argv.includes('--check')) {
+    const matches = fs.existsSync(jsonPath) && fs.readFileSync(jsonPath, 'utf8') === json &&
+      fs.existsSync(markdownPath) && fs.readFileSync(markdownPath, 'utf8') === markdown;
+    const blockers = coverage.rows.filter((row) => row.disposition === 'eligible' && row.status !== 'CURRENT');
+    if (!matches) console.error('source coverage projections differ from live observation');
+    if (argv.includes('--strict') && blockers.length) console.error(`strict coverage: ${blockers.length} eligible row(s) are not CURRENT`);
+    return matches && (!argv.includes('--strict') || blockers.length === 0) ? 0 : 1;
+  }
+  fs.writeFileSync(jsonPath, json);
+  fs.writeFileSync(markdownPath, markdown);
+  console.log(`wrote ${path.relative(ROOT, markdownPath)} (${coverage.rows.length} rows, ${coverage.coverageGeneration})`);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = await main();
+}

package/scripts/source-scope-receipt.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry === undefined ? null : entry)).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().filter((key) => value[key] !== undefined)
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export const digest = (value) => crypto.createHash('sha256')
+  .update(typeof value === 'string' ? value : canonicalJson(value)).digest('hex');
+
+const sha256File = (file) => {
+  const hash = crypto.createHash('sha256');
+  const bytes = fs.readFileSync(file);
+  hash.update(bytes);
+  return { sha256: hash.digest('hex'), bytes: bytes.length };
+};
+
+function gitInventory(root) {
+  const result = spawnSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+    cwd: root, encoding: 'buffer', maxBuffer: 128 * 1024 * 1024,
+  });
+  if (result.status !== 0) throw new Error(`repository inventory failed: ${String(result.stderr || '').trim()}`);
+  return result.stdout.toString('utf8').split('\0').filter(Boolean).sort();
+}
+
+function validateRelativeFile(root, relative) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative)
+    || relative.split(/[\\/]/).includes('..')) throw new Error(`unsafe source path: ${relative || '(missing)'}`);
+  const absolute = path.join(root, relative);
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`source path is not a regular file: ${relative}`);
+  return absolute;
+}
+
+function payload(receipt) {
+  const { receiptSha256: _receiptSha256, ...rest } = receipt;
+  return rest;
+}
+
+export function buildSourceScopeReceipt({ root, governedPaths, sourceSha = null, inventory = gitInventory } = {}) {
+  const repositoryRoot = path.resolve(root || '.');
+  const paths = inventory(repositoryRoot);
+  if (!paths.length || new Set(paths).size !== paths.length) throw new Error('repository inventory is empty or duplicated');
+  const files = paths.map((relative) => ({ path: relative, ...sha256File(validateRelativeFile(repositoryRoot, relative)) }));
+  const governed = [...new Set(governedPaths || [])].sort();
+  if (!governed.length) throw new Error('governed source scope is empty');
+  const inventorySet = new Set(paths);
+  const missing = governed.filter((relative) => !inventorySet.has(relative));
+  if (missing.length) throw new Error(`governed source is outside repository inventory: ${missing.join(', ')}`);
+  const byPath = new Map(files.map((row) => [row.path, row]));
+  const governedFiles = governed.map((relative) => ({ ...byPath.get(relative), readComplete: true }));
+  const body = {
+    schemaVersion: 1,
+    kind: 'ruvnet-brain-source-scope-receipt',
+    sourceSha,
+    repository: { fileCount: files.length, inventorySha256: digest(files) },
+    governed: { fileCount: governedFiles.length, files: governedFiles },
+  };
+  return { ...body, receiptSha256: digest(body) };
+}
+
+export function validateSourceScopeReceipt(receipt, { root, inventory = gitInventory } = {}) {
+  if (receipt?.schemaVersion !== 1 || receipt?.kind !== 'ruvnet-brain-source-scope-receipt'
+    || !Number.isInteger(receipt.repository?.fileCount) || !Array.isArray(receipt.governed?.files)
+    || receipt.governed.files.some((row) => row.readComplete !== true)) throw new Error('source scope receipt is malformed');
+  if (digest(payload(receipt)) !== receipt.receiptSha256) throw new Error('source scope receipt digest mismatch');
+  const rebuilt = buildSourceScopeReceipt({ root, sourceSha: receipt.sourceSha,
+    governedPaths: receipt.governed.files.map(({ path: relative }) => relative), inventory });
+  if (canonicalJson(rebuilt.repository) !== canonicalJson(receipt.repository)
+    || canonicalJson(rebuilt.governed) !== canonicalJson(receipt.governed)) {
+    throw new Error('source scope receipt differs from the current complete repository inventory');
+  }
+  return receipt;
+}