ruvnet-brain 4.3.20 → 4.3.25

package/console/scope.js

@@ -0,0 +1,209 @@
+/* scope.js — "what's in the brain". Reads /api/scope once, renders four verdict buckets and two
+   sortable, searchable tables. Every number on this page comes from that payload; nothing is typed
+   here. With JS off the page shows the as-of rule and an honest "needs the console server" line. */
+(function () {
+  'use strict';
+
+  /* ── theme toggle — same key and mechanism as the console ───────────────── */
+  var KEY = 'rbc-theme';
+  var btn = document.getElementById('theme-toggle');
+  if (btn) {
+    btn.addEventListener('click', function () {
+      var t = document.documentElement.dataset.theme === 'light' ? 'dark' : 'light';
+      document.documentElement.dataset.theme = t;
+      try { localStorage.setItem(KEY, t); } catch (e) { /* private mode is fine */ }
+    });
+  }
+
+  var $ = function (id) { return document.getElementById(id); };
+  var esc = function (s) {
+    return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
+      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+    });
+  };
+  var day = function (iso) { return iso ? String(iso).slice(0, 10) : null; };
+  var BUCKET = {
+    current:      { cls: 'b-current',    label: 'in the brain · current' },
+    behind:       { cls: 'b-behind',     label: 'in the brain · behind' },
+    unverified:   { cls: 'b-unverified', label: 'in the brain · currency unverified' },
+    'not-in-brain': { cls: 'b-notin',    label: 'not in the brain' }
+  };
+  var RANK = { current: 0, behind: 1, unverified: 2, 'not-in-brain': 3 };            // column sort on "verdict"
+  var RANK_BEHIND = { behind: 0, unverified: 1, 'not-in-brain': 2, current: 3 };     // the "Behind first" view
+
+  /* ── three views + one search, as pure functions (owner, 2026-09-12: "alphabetically, or
+     thematically, or by date"). Published on window.RBScope so the page and its test share them. ── */
+  function byName(a, b) {
+    return String(a.name || '').localeCompare(String(b.name || ''), undefined, { sensitivity: 'base' });
+  }
+  function newestFirst(a, b) {
+    var x = a.ruvChangedAt, y = b.ruvChangedAt;
+    if (x == null && y == null) return byName(a, b);
+    if (x == null) return 1;   // unknown dates sink to the bottom
+    if (y == null) return -1;
+    return x < y ? 1 : x > y ? -1 : byName(a, b);
+  }
+  /** Which comparator a named view uses. An unknown view reads as "newest", never throws. */
+  function sortFor(view) {
+    if (view === 'az') return byName;
+    if (view === 'behind') {
+      return function (a, b) {
+        var ra = RANK_BEHIND[a.bucket], rb = RANK_BEHIND[b.bucket];
+        var d = (ra == null ? 9 : ra) - (rb == null ? 9 : rb);
+        return d !== 0 ? d : newestFirst(a, b);
+      };
+    }
+    return newestFirst;
+  }
+  /** Does a row answer the query — by name, or by what it does (desc)? An empty query matches everything. */
+  function match(row, q) {
+    var needle = String(q == null ? '' : q).trim().toLowerCase();
+    if (!needle) return true;
+    return String(row.name || '').toLowerCase().indexOf(needle) !== -1
+      || String(row.desc || '').toLowerCase().indexOf(needle) !== -1;
+  }
+  window.RBScope = { match: match, sortFor: sortFor };
+
+  var VIEW_SORT = { newest: ['ruvChangedAt', 'desc'], az: ['name', 'asc'], behind: ['bucket', 'asc'] };
+  var state = { data: null, q: '', view: 'newest', sort: { repos: ['ruvChangedAt', 'desc'], gists: ['ruvChangedAt', 'desc'] } };
+
+  function cmp(key, dir) {
+    var m = dir === 'asc' ? 1 : -1;
+    return function (a, b) {
+      var x = a[key], y = b[key];
+      if (key === 'bucket') { x = RANK[x]; y = RANK[y]; }
+      // unknown dates always sink to the bottom, whichever direction is chosen
+      if (x == null && y == null) return a.name.localeCompare(b.name);
+      if (x == null) return 1;
+      if (y == null) return -1;
+      if (x < y) return -1 * m;
+      if (x > y) return 1 * m;
+      return a.name.localeCompare(b.name);
+    };
+  }
+
+  function rowHtml(r) {
+    var b = BUCKET[r.bucket] || BUCKET.unverified;
+    var gap = r.bucket === 'behind' && r.behindDays != null ? '<span class="gap">behind ' + r.behindDays + ' d</span>' : '';
+    var d1 = day(r.ruvChangedAt), d2 = day(r.brainReadAt);
+    return '<tr>' +
+      '<td class="name"><a href="' + esc(r.url) + '" target="_blank" rel="noopener">' + esc(r.name) + '</a>' +
+        (r.desc ? '<small class="desc" title="' + esc(r.desc) + '">' + esc(r.desc) + '</small>' : '') + '</td>' +
+      '<td class="date' + (d1 ? '' : ' unknown') + '">' + (d1 || 'unknown') + '</td>' +
+      '<td class="date' + (d2 ? '' : ' unknown') + '">' + (d2 || (r.bucket === 'not-in-brain' ? '—' : 'unknown')) + '</td>' +
+      '<td class="verdict"><span class="badge ' + b.cls + '">' + b.label + '</span>' + gap + '</td>' +
+      '<td class="sha" title="brain holds ' + esc(r.brainSha || '—') + ' · upstream ' + esc(r.upstreamSha || '—') + '">' +
+        esc((r.brainSha || '—').slice(0, 7)) + ' → ' + esc((r.upstreamSha || '—').slice(0, 7)) + '</td>' +
+    '</tr>';
+  }
+
+  function renderTable(kind) {
+    var rows = state.data[kind] || [];
+    var q = state.q.trim().toLowerCase();
+    if (q) rows = rows.filter(function (r) { return match(r, q); });
+    var s = state.sort[kind];
+    // a named view sorts both tables the same way; a column click switches to a per-table sort
+    rows = rows.slice().sort(state.view === 'custom' ? cmp(s[0], s[1]) : sortFor(state.view));
+    var body = $(kind + '-body');
+    var t0 = performance.now();
+    body.innerHTML = rows.length ? rows.map(rowHtml).join('') : '<tr><td colspan="5" class="empty">no ' + kind + ' match “' + esc(state.q) + '”</td></tr>';
+    $(kind + '-count').textContent = rows.length + (q ? ' of ' + (state.data[kind] || []).length : '');
+    var ths = $(kind + '-table').querySelectorAll('thead th[data-key]');
+    for (var i = 0; i < ths.length; i++) {
+      var k = ths[i].getAttribute('data-key');
+      ths[i].setAttribute('aria-sort', k === s[0] ? (s[1] === 'asc' ? 'ascending' : 'descending') : 'none');
+    }
+    if (window.console && rows.length > 200) console.debug('[scope] rendered', kind, rows.length, 'rows in', Math.round(performance.now() - t0), 'ms');
+  }
+
+  function renderBuckets(d) {
+    var c = d.counts || {};
+    var r = c.repos || {}, g = c.gists || {};
+    var tile = function (cls, key, label, desc) {
+      var n = (r[key] || 0) + (g[key] || 0);
+      return '<div class="bucket ' + cls + '"><div class="n">' + n + '<small>' + (r[key] || 0) + ' repos · ' + (g[key] || 0) + ' gists</small></div>' +
+        '<div class="l">' + label + '</div><div class="d">' + desc + '</div></div>';
+    };
+    $('buckets').innerHTML =
+      tile('b-current', 'current', 'in the brain · current', 'The brain holds exactly the commit (or gist revision) that is live upstream.') +
+      tile('b-behind', 'behind', 'in the brain · behind', 'rUv changed it after the brain last read it. The gap is shown per row.') +
+      tile('b-unverified', 'unverified', 'in the brain · unverified', 'Installed here, but no source commit was recorded, so currency cannot be proven either way.') +
+      tile('b-notin', 'notInBrain', 'not in the brain', 'Eligible upstream, no store on this machine.');
+    var inel = (r.ineligible || 0) + (g.ineligible || 0);
+    var foot = [];
+    if (inel) foot.push(inel + ' upstream item' + (inel === 1 ? '' : 's') + ' excluded by policy (forks, archived, empty) — not counted above');
+    if (d.installedOutsideCoverage && d.installedOutsideCoverage.length) {
+      foot.push(d.installedOutsideCoverage.length + ' store' + (d.installedOutsideCoverage.length === 1 ? '' : 's') + ' installed locally, outside release coverage: <code>' + d.installedOutsideCoverage.map(esc).join('</code>, <code>') + '</code>');
+    }
+    $('bucket-foot').innerHTML = foot.join(' · ');
+  }
+
+  function renderAsOf(d) {
+    var el = $('asof');
+    var age = d.ageDays == null ? null : Math.round(d.ageDays);
+    el.className = 'asof' + (d.stale ? ' is-old' : '');
+    el.innerHTML = '<span class="dot"></span>as of <strong>' + esc(day(d.observedAt) || 'unknown') + '</strong>' +
+      (age == null ? '' : ' · ' + age + ' day' + (age === 1 ? '' : 's') + ' ago') +
+      (d.releaseTag ? ' · brain ' + esc(d.releaseTag) : '') +
+      ' · ' + (d.installedStoreCount != null ? d.installedStoreCount + ' stores installed' : '');
+    $('asof-note').textContent = d.stale
+      ? 'This is the coverage record that shipped with the installed brain, not a live probe. Repos rUv changed since this date are not reflected until the brain updates.'
+      : 'This is the coverage record that shipped with the installed brain.';
+  }
+
+  function render() {
+    var d = state.data;
+    renderAsOf(d); renderBuckets(d); renderTable('repos'); renderTable('gists');
+    $('foot-root').textContent = d.root || '';
+  }
+
+  function setView(view) {
+    state.view = view;
+    var buttons = document.querySelectorAll('.scope-views .view');
+    for (var i = 0; i < buttons.length; i++) {
+      buttons[i].setAttribute('aria-pressed', buttons[i].getAttribute('data-view') === view ? 'true' : 'false');
+    }
+    if (VIEW_SORT[view]) { state.sort.repos = VIEW_SORT[view].slice(); state.sort.gists = VIEW_SORT[view].slice(); }
+    renderTable('repos'); renderTable('gists');
+  }
+
+  function wire() {
+    $('search').addEventListener('input', function (e) { state.q = e.target.value; renderTable('repos'); renderTable('gists'); });
+    var buttons = document.querySelectorAll('.scope-views .view');
+    for (var b = 0; b < buttons.length; b++) {
+      buttons[b].addEventListener('click', function (ev) { setView(ev.currentTarget.getAttribute('data-view')); });
+    }
+    ['repos', 'gists'].forEach(function (kind) {
+      var ths = $(kind + '-table').querySelectorAll('thead th[data-key]');
+      for (var i = 0; i < ths.length; i++) {
+        ths[i].addEventListener('click', function (ev) {
+          var k = ev.currentTarget.getAttribute('data-key');
+          var s = state.sort[kind];
+          state.sort[kind] = [k, s[0] === k && s[1] === 'desc' ? 'asc' : 'desc'];
+          state.view = 'custom'; // a column click is a per-table sort; no view button is pressed
+          var vb = document.querySelectorAll('.scope-views .view');
+          for (var j = 0; j < vb.length; j++) vb[j].setAttribute('aria-pressed', 'false');
+          renderTable(kind);
+        });
+      }
+    });
+  }
+
+  fetch('/api/scope', { cache: 'no-store' }).then(function (r) { return r.json(); }).then(function (d) {
+    var st = $('state');
+    if (!d || d.available === false) {
+      st.className = 'state error';
+      st.textContent = 'The installed brain has no coverage record on this machine' + (d && d.reason ? ' — ' + d.reason : '') + '. Nothing to list; nothing is being guessed.';
+      return;
+    }
+    st.hidden = true;
+    $('content').hidden = false;
+    state.data = d;
+    wire();
+    render();
+  }).catch(function (e) {
+    var st = $('state');
+    st.className = 'state error';
+    st.textContent = 'Could not reach /api/scope on the console server: ' + (e && e.message ? e.message : e);
+  });
+})();

package/console/tips.html

@@ -74,6 +74,7 @@
       <span class="brand-text">RuvNet Brain <span class="brand-sub">the other 90%</span></span>
     </div>
     <div class="head-right">
+      <a class="back-chip mono" href="scope.html">what's in the brain ›</a>
       <a class="back-chip mono" href="./">‹ console</a>
       <button class="theme-toggle" id="theme-toggle" type="button" aria-label="Switch color theme">
         <svg class="ic-sun" viewBox="0 0 24 24" aria-hidden="true">

package/kb/corpus-release-identity.mjs

@@ -0,0 +1,239 @@
+// kb/corpus-release-identity.mjs — the customer side of a corpus-only release (ADR-086 step 16).
+//
+// TWO IDENTITY DOMAINS, AND WHY CONFLATING THEM COST A NIGHTLY HALF-GIGABYTE.
+//
+// A customer bundle carries a RUNTIME identity: `brainVersion` / `releaseTag` in SOURCE.json,
+// stamped by scripts/build-bundle.mjs:333-334 as the semver of the code release that assembled it.
+// A CORPUS release carries a TRANSPORT identity: the GitHub tag `corpus-sha256-<64 hex>`, which is
+// a content address of the corpus archive and is not a version of anything.
+//
+// kb/forge-update.mjs's isBehind() treated release-tag identity as authoritative with one string
+// inequality. Measured on this fixture before this module existed (4 consecutive `--apply` runs
+// against ONE unchanged corpus release):
+//
+//     apply#1: exit=0 zipDownloads=1 behindReported=true
+//     apply#2: exit=0 zipDownloads=2 behindReported=true
+//     apply#3: exit=0 zipDownloads=3 behindReported=true
+//     apply#4: exit=0 zipDownloads=4 behindReported=true
+//     check:   exit=10 zipDownloads=4 behindReported=true
+//
+// `'corpus-sha256-aaa…' !== 'v4.9.0'` is true, and it stays true after a perfectly successful
+// install, because the landed bundle re-stamps `releaseTag: v4.9.0`. The comparison could never
+// converge. So the transport identity is recorded in its OWN field, `corpusReleaseTag`, written
+// atomically with the installation, and compared only against a corpus tag.
+//
+// THE COMPATIBILITY BOUNDARY (Dual, verbatim): "One releases/latest pointer cannot represent
+// independent newest corpora for multiple incompatible runtimes. Either explicitly support the
+// current approved runtime with safe rejection for older clients, or add version-aware discovery.
+// Never silently install incompatible code."
+//
+// And on how the pin must hold (Dual, verbatim): "Pinning survives only through enforced equality
+// to the approved shipped runtime and its executable hashes. Copying current-main package.json or
+// preserving a version string alone is insufficient."
+//
+// Hence RUNTIME-IDENTITY.json. It is written by bin/install.mjs — the owner-gated code release —
+// and names the sha256 of the executables that release placed into the KB tree. It is NEVER
+// produced by a bundle: build-bundle.mjs cannot see coverage-integrity.mjs (it is behind the
+// updater's dynamic load), which is precisely why that file is the right thing to pin to. The
+// updater re-hashes those bytes at update time; a declared version alone proves nothing and is
+// never sufficient on its own.
+//
+// FAIL-CLOSED, ALWAYS. Missing identity file, unreadable identity file, missing executable,
+// changed executable, or a corpus release built by a different runtime → the corpus release is
+// REFUSED. A client that cannot prove which approved runtime it is running does not get a corpus
+// release; it keeps the bundle it has and is told to re-run the installer.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+/** The corpus transport tag shape published by scripts/corpus-seed-publish.mjs's corpusSeedTag(). */
+export const CORPUS_TAG_PATTERN = /^corpus-sha256-[0-9a-f]{64}$/;
+
+/** The installer-written record of which approved runtime this KB belongs to. */
+export const INSTALLED_RUNTIME_FILE = 'RUNTIME-IDENTITY.json';
+
+/**
+ * Executables the runtime pin is bound to, relative to the KB root.
+ *
+ * `coverage-integrity.mjs` is the trusted coverage validator. It is placed by the installer
+ * (bin/install.mjs placeTrustedCoverageValidator) and CANNOT be supplied by a bundle, so its bytes
+ * are a real, non-spoofable fingerprint of the approved shipped runtime on this machine. Adding
+ * more installer-placed executables here widens the pin; nothing else needs to change.
+ */
+export const RUNTIME_PINNED_EXECUTABLES = Object.freeze(['coverage-integrity.mjs']);
+
+/** Where a refused release is remembered — OUTSIDE the governed tree, so an update cannot erase it. */
+export const REJECTED_RELEASE_FILE = '.ruvnet-brain-rejected-release.json';
+
+export function isCorpusReleaseTag(tag) {
+  return typeof tag === 'string' && CORPUS_TAG_PATTERN.test(tag);
+}
+
+function fileIdentity(file) {
+  try {
+    const bytes = fs.readFileSync(file);
+    return { sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length };
+  } catch {
+    return null;
+  }
+}
+
+function atomicJson(file, value) {
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(temp, file);
+}
+
+/**
+ * Stamp "this tree belongs to approved runtime X, and here are X's executable hashes" into `kbDir`.
+ *
+ * Called by the installer immediately after it places those executables, so the declared version and
+ * the measured bytes are written from the same moment and cannot disagree.
+ *
+ * @returns {{written: boolean, path: string, missing: string[]}}
+ */
+export function writeInstalledRuntimeIdentity(kbDir, { brainVersion }) {
+  if (!brainVersion || typeof brainVersion !== 'string') {
+    throw new Error('writeInstalledRuntimeIdentity requires the approved runtime brainVersion');
+  }
+  const executables = {};
+  const missing = [];
+  for (const relative of RUNTIME_PINNED_EXECUTABLES) {
+    const identity = fileIdentity(path.join(kbDir, relative));
+    if (!identity) { missing.push(relative); continue; }
+    executables[relative] = identity;
+  }
+  const target = path.join(kbDir, INSTALLED_RUNTIME_FILE);
+  // A pin naming an executable that is not there would be a pin to nothing. Refuse to write one.
+  if (missing.length) return { written: false, path: target, missing };
+  atomicJson(target, {
+    schemaVersion: 1,
+    kind: 'ruvnet-brain-installed-runtime',
+    brainVersion,
+    stampedUtc: new Date().toISOString(),
+    executables,
+  });
+  return { written: true, path: target, missing };
+}
+
+/**
+ * Read the installed approved runtime and RE-HASH every executable it pins.
+ *
+ * The declared `brainVersion` is only ever returned alongside proof that the bytes it was written
+ * against are still the bytes on disk — that is the whole difference between an enforced pin and a
+ * copied version string.
+ *
+ * @returns {{ok: boolean, brainVersion: string|null, reason: string|null}}
+ */
+export function readInstalledRuntime(kbDir) {
+  const file = path.join(kbDir, INSTALLED_RUNTIME_FILE);
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    return { ok: false, brainVersion: null,
+      reason: `no installed runtime identity at ${INSTALLED_RUNTIME_FILE} (${error.code === 'ENOENT' ? 'absent' : error.message})` };
+  }
+  if (doc?.schemaVersion !== 1 || doc?.kind !== 'ruvnet-brain-installed-runtime'
+    || typeof doc.brainVersion !== 'string' || !doc.brainVersion || !doc.executables) {
+    return { ok: false, brainVersion: null, reason: `${INSTALLED_RUNTIME_FILE} is not a readable installed-runtime record` };
+  }
+  const declared = Object.keys(doc.executables).sort();
+  const expected = [...RUNTIME_PINNED_EXECUTABLES].sort();
+  if (declared.join('\0') !== expected.join('\0')) {
+    return { ok: false, brainVersion: null,
+      reason: `${INSTALLED_RUNTIME_FILE} pins [${declared.join(', ')}], this runtime requires [${expected.join(', ')}]` };
+  }
+  for (const relative of expected) {
+    const measured = fileIdentity(path.join(kbDir, relative));
+    const pinned = doc.executables[relative];
+    if (!measured) {
+      return { ok: false, brainVersion: null, reason: `pinned runtime executable ${relative} is missing` };
+    }
+    if (measured.sha256 !== pinned?.sha256 || measured.bytes !== pinned?.bytes) {
+      return { ok: false, brainVersion: null,
+        reason: `pinned runtime executable ${relative} does not match its approved bytes `
+          + `(approved ${String(pinned?.sha256).slice(0, 12)}…/${pinned?.bytes}B, on disk ${measured.sha256.slice(0, 12)}…/${measured.bytes}B)` };
+    }
+  }
+  return { ok: true, brainVersion: doc.brainVersion, reason: null };
+}
+
+/**
+ * Decide whether this client may install the release now staged/offered.
+ *
+ * `offeredRuntimeVersion` is the brainVersion the candidate bundle declares — read from a STAGED
+ * tree that has already passed signature verification, never from the release payload's prose.
+ *
+ * @returns {{ok: boolean, reason: string|null, installedRuntime: string|null}}
+ */
+export function assertCorpusReleaseCompatible({ kbDir, offeredRuntimeVersion = null }) {
+  const runtime = readInstalledRuntime(kbDir);
+  if (!runtime.ok) return { ok: false, reason: runtime.reason, installedRuntime: null };
+  if (offeredRuntimeVersion == null) return { ok: true, reason: null, installedRuntime: runtime.brainVersion };
+  if (offeredRuntimeVersion !== runtime.brainVersion) {
+    return { ok: false, installedRuntime: runtime.brainVersion,
+      reason: `this corpus release was built by runtime ${offeredRuntimeVersion}; `
+        + `this brain runs approved runtime ${runtime.brainVersion}` };
+  }
+  return { ok: true, reason: null, installedRuntime: runtime.brainVersion };
+}
+
+/**
+ * Record the authenticated transport identity of the bytes now being installed, IN the tree being
+ * installed — so promotion carries it or nothing is promoted. The runtime identity fields
+ * (`brainVersion` / `releaseTag`) are never touched: they describe the code that built the bundle,
+ * and a corpus tag is not a version of that code.
+ */
+export function recordCorpusTransportIdentity(treeDir, { releaseTag }) {
+  const file = path.join(treeDir, 'SOURCE.json');
+  const source = JSON.parse(fs.readFileSync(file, 'utf8'));
+  // STRICTLY IDEMPOTENT, AND THAT IS NOT A STYLE CHOICE. A promoted tree's byte identity is what
+  // the storage transaction compares to decide `noop` vs `applied` — the distinction issue #106 and
+  // #108 were fought over. Rewriting SOURCE.json to set a field to the value it already holds (or
+  // to delete keys that were never there) re-serializes the file and changes its bytes, which turns
+  // a genuine no-op into a spurious "applied" and strands a rollback copy. So: touch the file only
+  // when a field actually changes. For the same reason there is no install timestamp here — a
+  // clock-valued field would differ on every run and could never be byte-identical. The tag IS the
+  // identity; `builtUtc` already carries the time.
+  if (isCorpusReleaseTag(releaseTag)) {
+    if (source.corpusReleaseTag === releaseTag) return source;
+    source.corpusReleaseTag = releaseTag;
+  } else {
+    // An ordinary code release supersedes whatever corpus generation preceded it: its bundle IS the
+    // corpus. Leaving a stale corpus tag behind would make the next check compare against a corpus
+    // this tree no longer holds.
+    if (!Object.hasOwn(source, 'corpusReleaseTag')) return source;
+    delete source.corpusReleaseTag;
+  }
+  atomicJson(file, source);
+  return source;
+}
+
+// ── the anti-loop ledger ────────────────────────────────────────────────────────────────────────
+// A refusal that is rediscovered every night is a download loop with extra steps. The refused tag
+// is remembered next to the KB (never inside it, where an update would replace it), so the very
+// next run refuses BEFORE fetching a byte. It is cleared the moment a different release is offered.
+
+export function rejectedReleasePath(kbDir) {
+  return path.join(path.dirname(path.resolve(kbDir)), REJECTED_RELEASE_FILE);
+}
+
+export function readRejectedRelease(kbDir) {
+  try {
+    const doc = JSON.parse(fs.readFileSync(rejectedReleasePath(kbDir), 'utf8'));
+    return typeof doc?.tag === 'string' && doc.tag ? doc : null;
+  } catch { return null; }
+}
+
+export function writeRejectedRelease(kbDir, { tag, reason, installedRuntime = null }) {
+  try {
+    atomicJson(rejectedReleasePath(kbDir), { schemaVersion: 1, kind: 'ruvnet-brain-rejected-release',
+      tag, reason, installedRuntime, rejectedUtc: new Date().toISOString() });
+    return true;
+  } catch { return false; } // never let bookkeeping mask the refusal itself
+}
+
+export function clearRejectedRelease(kbDir) {
+  try { fs.rmSync(rejectedReleasePath(kbDir), { force: true }); return true; } catch { return false; }
+}

package/kb/update-storage-transaction.mjs

@@ -48,12 +48,29 @@ export function treeIdentity(dir) {
     fileCount: entries.filter((entry) => entry.type === 'file').length, entries };
 }
 
+// SYMLINK POLICY (issues #130/#131, applied here 2026-09-11). This threw on ANY symbolic link, and
+// the installed brain always carries one: npm's `node_modules/.bin/semver`. So the already-current
+// path in forge-update.mjs (managedStorageInventory at :1141) died on every machine, and the same
+// link inside a `kb.bak-*` sibling wedged its inventory. A link that cannot be a store file and
+// stays inside the tree is inventory, reported as `symlinkCount`. Two cases still throw, because
+// they are what the hardening exists for: a link standing in for a store file, and a link that
+// escapes the tree (its target is what a receipt would then silently be measuring).
 function trustedTreeSummary(dir, kind) {
   const identity = treeIdentity(dir);
-  if (identity.entries.some((entry) => entry.type === 'symlink')) {
-    throw new Error(`managed ${kind} tree contains a symbolic link: ${dir}`);
+  const root = path.resolve(dir);
+  let symlinkCount = 0;
+  for (const entry of identity.entries) {
+    if (entry.type !== 'symlink') continue;
+    const relative = entry.path.split('/').join(path.sep);
+    const link = path.join(dir, relative);
+    if (/\.rvf$/i.test(relative)) throw new Error(`managed ${kind} tree contains a symbolic link in place of a store file: ${link}`);
+    const resolved = path.resolve(root, path.dirname(relative), entry.target);
+    if (path.isAbsolute(entry.target) || !resolved.startsWith(`${root}${path.sep}`)) {
+      throw new Error(`managed ${kind} tree contains a symbolic link that escapes the tree: ${link} -> ${entry.target}`);
+    }
+    symlinkCount++;
   }
-  return { kind, path: dir, sha256: identity.sha256, bytes: identity.bytes, fileCount: identity.fileCount };
+  return { kind, path: dir, sha256: identity.sha256, bytes: identity.bytes, fileCount: identity.fileCount, symlinkCount };
 }
 
 // Installer-retained paths are observations, not transaction-owned cleanup candidates. Count link

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.20",
+  "version": "4.3.25",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -33,10 +33,13 @@
     "qe:ux": "node scripts/qe/ux-suite.mjs",
     "test:cov": "vitest run tests/unit --coverage",
     "coverage:source": "node scripts/source-coverage.mjs --check",
+    "private-overlay": "node scripts/private-overlay.mjs",
+    "seal-gist-receipt": "node scripts/seal-gist-receipt.mjs",
     "test:all": "npm run test:unit && npm run test:mesh && npm run test:mutation && npm run test:regression && npm run test:integration && npm test",
     "metaharness:receipts": "node scripts/metaharness-receipts.mjs",
     "route:cheap": "node scripts/route-cheap.mjs",
     "route:receipt": "node scripts/dispatch-receipt.mjs",
+    "trismart": "node scripts/trismart.mjs",
     "metaharness:fix": "node scripts/fix-metaharness-memretrieve.mjs --apply",
     "metaharness:check": "node scripts/fix-metaharness-memretrieve.mjs --check",
     "eval": "node scripts/eval-brain.mjs",
@@ -64,7 +67,8 @@
     "cap:report": "node scripts/rerank-cap-eval.mjs --report",
     "cap:ab": "node scripts/rerank-cap-warm-ab.mjs",
     "hooks:check": "node scripts/hook-retirement-check.mjs",
-    "release:qualify": "node scripts/release-qualification.mjs"
+    "release:qualify": "node scripts/release-qualification.mjs",
+    "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs"
   },
   "files": [
     ".claude-plugin/marketplace.json",
@@ -84,10 +88,12 @@
     "LICENSE",
     "console/",
     "config/model-router/",
+    "tri-smart-skill/",
     "data/model-catalog.json",
     "scripts/",
     "kb/verify-citation.mjs",
     "kb/retrieval-result.mjs",
+    "kb/corpus-release-identity.mjs",
     "kb/zip-extract.mjs",
     "kb/brain-profile.mjs",
     "kb/lifecycle-evidence-retention.mjs",
@@ -125,6 +131,7 @@
     "@metaharness/darwin": "~0.9.2",
     "@ruvector/rvf": "^0.3.4",
     "@vitest/coverage-v8": "^4.1.10",
+    "mdast-util-from-markdown": "2.0.3",
     "playwright": "^1.62.0",
     "vitest": "^4.1.10"
   },

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.3.20",
+  "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
+  "version": "4.3.25",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.20",
+  "version": "4.3.25",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/commands/checkpoint.md

@@ -0,0 +1,61 @@
+---
+description: "Write a full project checkpoint to this project's canonical AgentDB store — the goal, the acceptance contract, the decisions, what is done, what is blocked, and the exact next action — so the next session (in Claude Code or Codex) resumes from a verified record instead of from nothing. Prints a read-back receipt."
+updated: 2026-09-11
+---
+
+# RuvNet-Brain: checkpoint
+
+The user is asking you to **persist the state of this project** so the next session can resume it.
+
+Automatic capture already runs at Stop, PreCompact and SessionEnd, and it records everything that can
+be READ from the machine: the git tree, their work ledger, their newest `project-state-current` note,
+a bounded transcript reference. **It cannot read what only you know** — the acceptance contract you
+are working to, the decision you just made and why, the exact next action. That is what this command
+is for, and it is why a checkpoint is worth more than another automatic snapshot.
+
+## Do this
+
+**1. Write down the real state — from THIS session, not from a template.**
+
+Build a JSON object with the fields you can honestly fill. Every field is optional; set at least one.
+Empty is better than invented: a fabricated "next action" is worse than no next action, because the
+next session will act on it.
+
+| field | what goes in it |
+|---|---|
+| `currentGoal` | one sentence: what this work is actually for |
+| `acceptanceContract` | what would make it DONE — the conditions, not the vibe |
+| `nextAction` | the single next concrete step, specific enough to start cold |
+| `decisions` | decisions made and WHY; include the ones you'd otherwise have to re-derive |
+| `completed` / `inProgress` / `blockers` | honest status; a blocker named is a blocker halved |
+| `failures` | what was tried and did not work, so it is not tried again |
+| `changedFiles` | the files this work touched |
+| `proofArtifacts` | commands run, outputs seen, receipts — the evidence, not the claim |
+| `untested` | what was built but NOT verified. Do not omit this one. |
+
+**2. Store it.**
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/project-progression-checkpoint.mjs" --json '<your JSON>'
+```
+
+For anything longer than a line or two, write the JSON to a temp file first and use
+`--json-file <path>` — a large single-quoted argument is how a shell mangles a checkpoint.
+
+**3. Report the receipt, not a claim.**
+
+The command prints the exact event key, the payload digest, and the digest of the row **read back
+from the store by that exact key**. Tell the user it is stored only when `readbackVerified` is
+`true`. If the command exits non-zero, say exactly what it printed — an unstored checkpoint that is
+reported as stored is the specific failure this whole system exists to prevent.
+
+If it reports `replayedPending`, say so: those were snapshots a previously interrupted session had
+made durable but never committed, and this checkpoint settled them.
+
+## What NOT to do
+
+- **Do not** invent progress, decisions, or proof to make the checkpoint look complete.
+- **Do not** write the user's secrets into it. Redaction runs anyway, but do not rely on it.
+- **Do not** hand-write rows into `.swarm/memory.db` or call `ruflo memory store` yourself. This
+  command is the one writer; a second path is how two stores drift apart.
+- **Do not** claim the next session "will remember" anything the receipt did not confirm.