ruvnet-brain 4.0.90-dev → 4.2.2-dev

package/scripts/ingest-new-repos.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * ingest-new-repos.mjs — load what rUv shipped, without being asked.
+ *
+ * THE GAP THIS CLOSES, and it is embarrassing rather than subtle. The owner asked on 2026-08-20
+ * why `ruvnet/ultrasonic` was not in the brain: *"aren't you loading everything Ruv creates every
+ * day?????"* The honest answer was no, and nothing ever had. `nightly-wrapper.sh` refreshed
+ * lessons, health, the release watchdog and the replay proof — and contained ZERO references to
+ * ingestion. New rUv repos only ever entered the brain when a human typed `ingest-repo.mjs` by
+ * hand, so the corpus drifted behind the org silently and the only symptom was a question the
+ * brain could not answer.
+ *
+ * `brain-stamp.mjs` already COMPUTES built-vs-pending every night. Nothing acted on it. Measuring
+ * a gap and never closing it is how 137 repos stayed uningested while the scorecard reported the
+ * number cheerfully.
+ *
+ * WHY IT IS BOUNDED. Ingestion embeds a whole repository; doing 137 in one night would run for
+ * hours and starve everything after it in the nightly. `--max` (default 3) keeps the nightly
+ * bounded and lets the corpus converge over days instead of blocking on one enormous run. That is
+ * a deliberate trade, and the run SAYS how many remain rather than implying it finished.
+ *
+ * WHAT IT WILL NOT DO. It does not write capability cards. An ingested store with no card is DARK —
+ * valid bytes that no by-description query can reach — and `ingest-repo.mjs` already says so on
+ * every run. Inventing a card from a repo name would put a confident description in the routing
+ * layer that nobody grounded in the source, which is worse than an honest gap: it would route real
+ * questions to a corpus that cannot answer them. So this reports the dark stores it created and
+ * leaves the card to someone who reads the repo.
+ *
+ *   node scripts/ingest-new-repos.mjs                 # report only
+ *   node scripts/ingest-new-repos.mjs --apply         # ingest up to --max new repos
+ *   node scripts/ingest-new-repos.mjs --apply --max 5
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { storeRoot, storesAt, darkStores } from '../kb/store-root.mjs';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
+const APPLY = process.argv.includes('--apply');
+const arg = (n, d) => {
+  const i = process.argv.indexOf(n);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d;
+};
+const MAX = Number(arg('--max', '3'));
+
+/** Every repo the org actually has right now. Live, never a remembered list. */
+function liveOrgRepos() {
+  try {
+    const out = execFileSync('gh', [
+      'repo', 'list', OWNER, '--limit', '500', '--no-archived', '--json', 'name,isFork,pushedAt,diskUsage',
+    ], { cwd: ROOT, encoding: 'utf8', maxBuffer: 1 << 26 });
+    return JSON.parse(out)
+      .filter((r) => !r.isFork)
+      // AN EMPTY REPO IS NOT A FAILURE TO RETRY FOREVER (measured 2026-08-20).
+      //
+      // The first bulk run reported 7 failures; six of them are size=0KB — genuinely empty
+      // repositories (socket, Auto-GPT, CodeGPT, ruvGPT2, rUvGPT, AIConverse). `git fetch` succeeds
+      // and there is simply nothing to embed, so ingestion fails correctly and then the repo stays
+      // "missing", so the NEXT night retries it, forever. A permanent nightly failure that is
+      // actually correct behaviour trains the reader to ignore the failure line — which is how a
+      // real failure would then hide inside it.
+      .filter((r) => Number(r.diskUsage ?? 1) > 0)
+      // Newest first: if the budget only allows a few tonight, spend it on what rUv shipped most
+      // recently, which is what a question is most likely to be about.
+      .sort((a, b) => String(b.pushedAt).localeCompare(String(a.pushedAt)))
+      .map((r) => r.name);
+  } catch (error) {
+    return { error: error?.message || String(error) };
+  }
+}
+
+export function pendingRepos(orgRepos, root = storeRoot()) {
+  const have = new Set(storesAt(root).map((s) => String(s).toLowerCase()));
+  return orgRepos.filter((name) => !have.has(String(name).toLowerCase()));
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const repos = liveOrgRepos();
+  if (!Array.isArray(repos)) {
+    // A LIST WE COULD NOT FETCH IS NOT AN EMPTY LIST. Reporting "0 new repos" here would read as
+    // "the brain is current" when the truth is "I could not look" — the exact conflation this
+    // repository keeps paying for.
+    console.error(`[ingest-new] could NOT list ${OWNER}'s repos: ${repos.error}`);
+    console.error('[ingest-new] this is NOT "nothing new" — it is "I could not look". Exiting 1.');
+    process.exit(1);
+  }
+
+  const root = storeRoot();
+  const missing = pendingRepos(repos, root);
+  console.log(`[ingest-new] ${OWNER}: ${repos.length} live repos, ${storesAt(root).length} ingested, ${missing.length} missing`);
+  if (!missing.length) { console.log('[ingest-new] corpus is level with the org.'); process.exit(0); }
+
+  console.log(`[ingest-new] next up (newest first): ${missing.slice(0, MAX).join(', ')}`);
+  if (!APPLY) {
+    console.log(`[ingest-new] report only. Re-run with --apply to ingest up to ${MAX}.`);
+    process.exit(0);
+  }
+
+  let done = 0; let failed = 0;
+  for (const name of missing.slice(0, MAX)) {
+    console.log(`\n[ingest-new] ingesting ${name}`);
+    const r = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'ingest-repo.mjs'), '--name', name],
+      { cwd: ROOT, stdio: 'inherit', env: process.env, timeout: 45 * 60_000 });
+    if (r.status === 0) done += 1;
+    else { failed += 1; console.log(`[ingest-new] ${name} FAILED — left missing so the next run retries it`); }
+  }
+
+  const stillMissing = missing.length - done;
+  const dark = darkStores(root);
+  console.log(`\n[ingest-new] ingested ${done}, failed ${failed}, ${stillMissing} still missing.`);
+  if (dark.length) {
+    console.log(`[ingest-new] ${dark.length} store(s) are DARK — valid bytes no by-description query can reach.`);
+    console.log('[ingest-new] a card is a claim about what a repo is FOR; write it from the source, not the name.');
+  }
+  process.exit(failed ? 1 : 0);
+}

package/scripts/nightly-wrapper.sh

@@ -7,6 +7,29 @@
 # class a blind retry can fix) -> if it fails AGAIN, loud phone alert + a durable marker file that
 # ground-ruvnet.sh surfaces at the top of the very next session, unprompted. Success or a legitimate
 # "nothing was due tonight" no-op: log only, phone stays silent.
+
+# WHICH NODE RUNS THIS DECIDES WHETHER TONIGHT'S WRITES SURVIVE (measured 2026-08-20).
+#
+# This file hardcoded "$NODE_BIN" in eight places. That is node v22.13.1 (ABI 127), and the
+# better-sqlite3 binding agentdb needs is built for ABI 137 — so under it agentdb SILENTLY falls
+# back to non-persistent sql.js and every write is lost. Silently, because better-sqlite3 is an
+# OPTIONAL dependency (ruvnet/ruflo#2219): the failure never errors and the CLI still prints a
+# success table. `lesson-bridge.mjs --apply` and `learning-replay.mjs` both write, so the nightly
+# was discarding its own results. Measured, same command, same DB, only the interpreter differing:
+#   "$NODE_BIN"   v22.13.1  ->  2 sql.js fallback msgs, DURABLE=NO
+#   /opt/homebrew/bin/node v24.18.0 ->  0 fallback msgs,        DURABLE=YES
+# Resolve a node whose ABI matches the binding, and fail loudly rather than silently losing data.
+NODE_BIN=""
+for _cand in /opt/homebrew/opt/node@24/bin/node /opt/homebrew/bin/node "$(command -v node 2>/dev/null)"; do
+  [ -x "$_cand" ] || continue
+  if [ "$("$_cand" -p 'process.versions.modules' 2>/dev/null)" = "137" ]; then NODE_BIN="$_cand"; break; fi
+done
+if [ -z "$NODE_BIN" ]; then
+  echo "[nightly] FATAL: no node with ABI 137 found — agentdb writes would silently not persist." >&2
+  echo "[nightly] checked: /opt/homebrew/opt/node@24/bin/node /opt/homebrew/bin/node \$(command -v node)" >&2
+  exit 1
+fi
+
 set -u
 # kb/models-cache (the fallback) starts cold every time -> every nightly re-downloads the ONNX
 # embedder from HuggingFace. Point at the already-warm cache instead (verified present).
@@ -55,9 +78,9 @@ run_once() {
   { echo "===== nightly-wrapper rebuild attempt $1 — $(date -u +%FT%TZ) ====="
     if [ "$SMOKE" = "1" ]; then
       echo "[SMOKE] dry-run: exercising the full chain, NOT building"
-      /usr/local/bin/node scripts/self-update.mjs --fresh-window 60
+      "$NODE_BIN" scripts/self-update.mjs --fresh-window 60
     else
-      /usr/local/bin/node scripts/self-update.mjs --apply --fresh-window 60
+      "$NODE_BIN" scripts/self-update.mjs --apply --fresh-window 60
     fi
   } >> "$LOG" 2>&1
   rc=$?
@@ -93,7 +116,7 @@ RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory backup --db .swarm/memor
 # it REFUSES to apply when it reads zero rows while bridged lessons are installed — so a transient
 # read failure can never strip the store. Best-effort, never blocks the rebuild.
 echo "===== lesson-bridge — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node plugin/scripts/lesson-bridge.mjs --apply >> "$LOG" 2>&1 \
+"$NODE_BIN" plugin/scripts/lesson-bridge.mjs --apply >> "$LOG" 2>&1 \
   || echo "===== lesson-bridge: SKIPPED (see line above) =====" >> "$LOG"
 
 # AgentDB drift canary (2026-07-23, P7 wiring sweep) — scripts/memdb-health.sh existed unwired since
@@ -141,15 +164,27 @@ sh scripts/memdb-health.sh .swarm/memory.db >> "$LOG" 2>&1 \
 # REPORTS ONLY. It cannot push, merge, close or publish (asserted by test). Exit 1 means a human
 # needs to look, and the reasons print in full rather than as a count.
 echo "===== GITHUB-HEALTH watch — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node scripts/github-health-watch.mjs >> "$LOG" 2>&1 \
+# LOAD WHAT rUv SHIPPED, WITHOUT BEING ASKED (added 2026-08-20).
+#
+# The owner: "aren't you loading everything Ruv creates every day?????" The answer was no — this
+# file had ZERO ingestion, so new repos only entered the brain when a human typed the command.
+# Measured the day this landed: 181 live repos, 69 ingested, 125 missing. `brain-stamp.mjs` had
+# been COMPUTING that gap nightly and nothing acted on it.
+#
+# Bounded to 3/night on purpose: ingestion embeds a whole repository, and 125 in one run would
+# starve everything after it here. The corpus converges over days and the run says how many
+# remain rather than implying it finished. A failed repo is left missing so the next night retries.
+"$NODE_BIN" scripts/ingest-new-repos.mjs --apply --max 3 >> "$LOG" 2>&1 || true
+
+"$NODE_BIN" scripts/github-health-watch.mjs >> "$LOG" 2>&1 \
   || echo "[github-health] findings above need attention" >> "$LOG"
 
 echo "===== RELEASE-CONVERGENCE watchdog — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node scripts/release-convergence-watchdog.mjs --dispatch >> "$LOG" 2>&1 \
+"$NODE_BIN" scripts/release-convergence-watchdog.mjs --dispatch >> "$LOG" 2>&1 \
   || echo "[release-watchdog] exited non-zero — see above; nightly continues" >> "$LOG"
 
 echo "===== LEARNING-REPLAY counterfactual trap — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node scripts/learning-replay.mjs --n 3 --model haiku >> "$LOG" 2>&1
+"$NODE_BIN" scripts/learning-replay.mjs --n 3 --model haiku >> "$LOG" 2>&1
 LR_RC=$?
 case "$LR_RC" in
   0) echo "===== LEARNING-REPLAY: PASS =====" >> "$LOG" ;;
@@ -165,7 +200,7 @@ esac
 BRAIN_KB="$HOME/.cache/ruvnet-brain/kb"
 if [ -f "$BRAIN_KB/forge-ask-all.mjs" ]; then
   echo "===== brain-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
-  if (cd "$BRAIN_KB" && /usr/local/bin/node forge-ask-all.mjs --dir . --q "HNSW vector index" --k 1) >> "$LOG" 2>&1; then
+  if (cd "$BRAIN_KB" && "$NODE_BIN" forge-ask-all.mjs --dir . --q "HNSW vector index" --k 1) >> "$LOG" 2>&1; then
     echo "===== brain-health canary: OK =====" >> "$LOG"
   else
     echo "===== brain-health canary: DOWN — escalating =====" >> "$LOG"
@@ -181,7 +216,7 @@ fi
 # The canary itself handles urgent pushes on alive->DEAD transitions (and recovery notices), so a
 # known-dead key doesn't re-alarm every night; here we only log.
 echo "===== key-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
-zsh -lc 'cd /Users/stuartkerr/Code/ruvnet-brain && /usr/local/bin/node scripts/key-canary.mjs --notify' >> "$LOG" 2>&1 \
+zsh -lc 'cd /Users/stuartkerr/Code/ruvnet-brain && "$NODE_BIN" scripts/key-canary.mjs --notify' >> "$LOG" 2>&1 \
   && echo "===== key-health canary: all present keys alive =====" >> "$LOG" \
   || echo "===== key-health canary: at least one key DEAD (push sent on new deaths) =====" >> "$LOG"
 

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

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// Deterministically reconstruct gist passages from tracked, 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 path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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 (![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,
+  };
+  return {
+    passages,
+    passageBody,
+    meta,
+    sources: { ...source, schemaVersion: 2, passagesSha256: sha256(passageBody), 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;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const allowed = new Set(['--sources', '--out-dir', '--concurrency']);
+  for (let index = 0; index < argv.length; index += 2) {
+    if (!allowed.has(argv[index]) || !argv[index + 1] || argv[index + 1].startsWith('--')) fail(`unknown or incomplete option ${argv[index] || '(missing)'}`);
+  }
+  const sourcesFile = path.resolve(option(argv, '--sources', path.join(ROOT, 'kb', `${NAME}.sources.json`)));
+  const 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 });
+  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;
+  });
+}

package/scripts/release-transaction.mjs

@@ -55,10 +55,36 @@ export const ALLOWED_TRANSITIONS = Object.freeze({
   aborted: [],
 });
 
+/**
+ * THE DIGEST SERIALISER MUST AGREE WITH THE ONE THAT WRITES THE FILE.
+ *
+ * It did not, and it silently corrupted the terminal receipt of EVERY successful release. Measured
+ * 2026-08-20 on v4.0.36 and v4.0.90-dev — both `channels-converged` receipts, both digest=BAD, both
+ * with the same missing key:
+ *
+ *     canonicalJson({a: undefined})  ->  {"a":undefined}      key KEPT (and not even valid JSON)
+ *     JSON.stringify({a: undefined}) ->  {}                   key DROPPED
+ *
+ * The converge observation carries optional fields — `hosts.verifier.error`, `claudeOnly`,
+ * `codexOnly`, `dual` — and on a clean run `verified.error` is `undefined`. So the digest was
+ * computed over `…"error":undefined…` while the bytes written omitted `error` entirely: a digest
+ * over a shape that can never be read back. `runReleaseTransaction` appends a receipt, reads it
+ * back and verifies it, so the publish then died with `release receipt digest mismatch` AFTER npm
+ * and GitHub had both been promoted — the release shipped and the rail reported failure.
+ *
+ * Proven by reconstruction: restoring `observation.hosts.verifier.error = undefined` on the stored
+ * receipt makes `digestReceipt` reproduce the stored digest exactly.
+ *
+ * Arrays have the same asymmetry (`JSON.stringify([undefined])` is `[null]`), so both are matched
+ * here. This does not change the digest of any receipt that never held an undefined value, which is
+ * every receipt that currently verifies.
+ */
 export const canonicalJson = (value) => {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (Array.isArray(value)) return `[${value.map((item) => (item === undefined ? 'null' : canonicalJson(item))).join(',')}]`;
   if (value && typeof value === 'object') {
-    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+    return `{${Object.keys(value).sort()
+      .filter((key) => value[key] !== undefined)
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
   }
   return JSON.stringify(value);
 };
@@ -86,6 +112,8 @@ export const transactionIdFor = (identity) => crypto.createHash('sha256').update
   bundleSha256: identity.bundleSha256,
   bundleSignatureSha256: identity.bundleSignatureSha256 || null,
   bundleDigestSha256: identity.bundleDigestSha256 || null,
+  ...(identity.corpusSeedSha256 ? { corpusSeedSha256: identity.corpusSeedSha256 } : {}),
+  ...(identity.generationLedgerSha256 ? { generationLedgerSha256: identity.generationLedgerSha256 } : {}),
 })).digest('hex');
 
 export function signReceipt(receipt, privateKey) {