ruvnet-brain 3.9.84-dev → 3.9.129-dev

package/kb/brain-profile.mjs

@@ -0,0 +1,145 @@
+// brain-profile.mjs — enforce the user's installed knowledge profile by artifact family.
+//
+// Each repository is already one independent RVF + sidecar family. "RuVector only" therefore means
+// keeping the shared reader plus the ruvector family, not rebuilding or copying a second brain.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PROFILE_COMPLETE = 'complete';
+export const PROFILE_RUVECTOR = 'ruvector';
+export const BRAIN_PROFILES = Object.freeze([PROFILE_COMPLETE, PROFILE_RUVECTOR]);
+
+export function settingsPath(env = process.env) {
+  return env.RUVNET_SETTINGS_FILE
+    || path.join(os.homedir(), '.config', 'ruvnet-brain', 'settings.json');
+}
+
+export function readBrainProfile({ env = process.env } = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(settingsPath(env), 'utf8'));
+    const value = parsed?.settings?.brainProfile;
+    return BRAIN_PROFILES.includes(value) ? value : PROFILE_COMPLETE;
+  } catch {
+    return PROFILE_COMPLETE;
+  }
+}
+
+export function discoverStoreFamilies(dir) {
+  const names = new Set();
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  for (const entry of entries) {
+    const match = entry.match(/^(.+?)(?:\.big)?\.rvf$/);
+    if (match && !/\.(?:idmap|embed)\b/.test(entry)) names.add(match[1]);
+  }
+  return [...names].sort();
+}
+
+function familyEntries(dir, store) {
+  return fs.readdirSync(dir).filter((entry) =>
+    entry === `${store}-primer.md` || entry === store || entry.startsWith(`${store}.`));
+}
+
+function filterCapabilityCards(dir) {
+  const file = path.join(dir, 'capability-cards.md');
+  if (!fs.existsSync(file)) return;
+  const backup = path.join(dir, 'capability-cards.complete.md');
+  const current = fs.readFileSync(file, 'utf8');
+  const cardCount = (current.match(/^## /gm) || []).length;
+  if (!fs.existsSync(backup) || cardCount > 1) fs.copyFileSync(file, backup);
+  const full = fs.readFileSync(backup, 'utf8');
+  const firstCard = full.search(/^## /m);
+  const start = full.search(/^## ruvector\s*$/m);
+  if (firstCard < 0 || start < 0) throw new Error('could not isolate the RuVector capability card');
+  const rest = full.slice(start);
+  const next = rest.slice(1).search(/^## /m);
+  const card = next < 0 ? rest : rest.slice(0, next + 1);
+  fs.writeFileSync(file, `${full.slice(0, firstCard)}${card.trimEnd()}\n`);
+}
+
+function restoreCapabilityCards(dir) {
+  const backup = path.join(dir, 'capability-cards.complete.md');
+  if (fs.existsSync(backup)) fs.copyFileSync(backup, path.join(dir, 'capability-cards.md'));
+}
+
+function filterGenerationLedger(dir, allowed) {
+  const file = path.join(dir, 'RVF-GENERATIONS.json');
+  if (!fs.existsSync(file)) return;
+  const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+  doc.stores = Object.fromEntries(Object.entries(doc.stores || {}).filter(([name]) => allowed.has(name)));
+  fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
+}
+
+export function applyBrainProfile(dir, profile) {
+  if (!BRAIN_PROFILES.includes(profile)) throw new Error(`unknown brain profile: ${profile}`);
+  if (profile === PROFILE_COMPLETE) {
+    restoreCapabilityCards(dir);
+    return { profile, removed: [], bytesFreed: 0, stores: discoverStoreFamilies(dir) };
+  }
+
+  const allowed = new Set([PROFILE_RUVECTOR]);
+  const removed = [];
+  const removedStores = [];
+  let bytesFreed = 0;
+  for (const store of discoverStoreFamilies(dir)) {
+    if (allowed.has(store)) continue;
+    removedStores.push(store);
+    for (const entry of familyEntries(dir, store)) {
+      const target = path.join(dir, entry);
+      try { bytesFreed += fs.statSync(target).size; } catch { /* report only measured bytes */ }
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(entry);
+    }
+  }
+  filterCapabilityCards(dir);
+  filterGenerationLedger(dir, allowed);
+  return { profile, removed, removedStores, bytesFreed, stores: discoverStoreFamilies(dir) };
+}
+
+export function restoreCompleteProfile(targetDir, sourceDir) {
+  if (!discoverStoreFamilies(sourceDir).includes(PROFILE_RUVECTOR)) {
+    throw new Error(`complete bundle source is unavailable at ${sourceDir}`);
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  const stores = discoverStoreFamilies(sourceDir);
+  for (const store of stores) {
+    for (const entry of familyEntries(sourceDir, store)) {
+      fs.cpSync(path.join(sourceDir, entry), path.join(targetDir, entry), {
+        recursive: true,
+        force: true,
+      });
+    }
+  }
+  for (const entry of ['capability-cards.md', 'RVF-GENERATIONS.json']) {
+    const source = path.join(sourceDir, entry);
+    if (fs.existsSync(source)) fs.copyFileSync(source, path.join(targetDir, entry));
+  }
+  const cards = path.join(sourceDir, 'capability-cards.md');
+  if (fs.existsSync(cards)) {
+    fs.copyFileSync(cards, path.join(targetDir, 'capability-cards.complete.md'));
+  }
+  return { profile: PROFILE_COMPLETE, stores: discoverStoreFamilies(targetDir) };
+}
+
+export function measureBrainProfile(dir) {
+  const stores = discoverStoreFamilies(dir);
+  const byStore = {};
+  let bytes = 0;
+  for (const store of stores) {
+    let storeBytes = 0;
+    for (const entry of familyEntries(dir, store)) {
+      const target = path.join(dir, entry);
+      const walk = (p) => {
+        const stat = fs.statSync(p);
+        if (!stat.isDirectory()) { storeBytes += stat.size; return; }
+        for (const child of fs.readdirSync(p)) walk(path.join(p, child));
+      };
+      try { walk(target); } catch { /* a changing file is omitted from the measurement */ }
+    }
+    byStore[store] = storeBytes;
+    bytes += storeBytes;
+  }
+  return { stores, storeCount: stores.length, bytes, byStore };
+}

package/kb/model-requirements.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const MINILM_MODEL = 'Xenova/all-MiniLM-L6-v2';
+export const BGE_MODEL = 'Xenova/bge-base-en-v1.5';
+
+export function modelPath(modelCache, model) {
+  return path.join(modelCache, ...model.split('/'));
+}
+
+export function modelCacheReady(modelCache, model, revision = null) {
+  const root = revision
+    ? path.join(modelPath(modelCache, model), revision)
+    : modelPath(modelCache, model);
+  return [
+    path.join(root, 'tokenizer.json'),
+    path.join(root, 'config.json'),
+    path.join(root, 'onnx', 'model_quantized.onnx'),
+  ].every((file) => fs.existsSync(file));
+}
+
+// Revision-pinned downloads live below <model>/<revision>/, while strict offline reads resolve
+// <model>/ directly. Promote only the exact pinned files into that canonical offline location.
+export function materializeModelRevision(modelCache, model, revision) {
+  if (!revision || !modelCacheReady(modelCache, model, revision)) return false;
+  const source = path.join(modelPath(modelCache, model), revision);
+  const destination = modelPath(modelCache, model);
+  for (const entry of fs.readdirSync(source)) {
+    fs.cpSync(path.join(source, entry), path.join(destination, entry), {
+      recursive: true,
+      force: true,
+    });
+  }
+  return modelCacheReady(modelCache, model);
+}
+
+// The RVF sidecar is the source of truth for the query embedder. Only sidecars with a matching
+// installed RVF count; stale/orphan metadata must not make a healthy installation look cold.
+export function requiredEmbedderModels(kbDir) {
+  const models = new Set();
+  try {
+    for (const file of fs.readdirSync(kbDir)) {
+      if (!file.endsWith('.rvf.embed.json')) continue;
+      const rvf = file.slice(0, -'.embed.json'.length);
+      if (!fs.existsSync(path.join(kbDir, rvf))) continue;
+      if (!rvf.endsWith('.big.rvf')) {
+        const name = rvf.slice(0, -'.rvf'.length);
+        if (fs.existsSync(path.join(kbDir, `${name}.big.rvf`))) continue;
+      }
+      try {
+        const model = JSON.parse(fs.readFileSync(path.join(kbDir, file), 'utf8'))?.model;
+        if (typeof model === 'string' && model.includes('/')) models.add(model);
+      } catch { /* unreadable metadata proves no requirement */ }
+    }
+  } catch { /* absent KB falls through to the legacy small-store default */ }
+  return models.size ? [...models].sort() : [MINILM_MODEL];
+}
+
+export function missingEmbedderModels(modelCache, models) {
+  return models.filter((model) => !fs.existsSync(modelPath(modelCache, model)));
+}
+
+export function configureTransformersModel(T, modelCache, model) {
+  const local = modelCacheReady(modelCache, model);
+  T.env.localModelPath = modelCache;
+  // Transformers.js otherwise downloads into its package-local `.cache`, while every doctor and
+  // release detector inspects `modelCache`. A download invisible to the runtime's own detector
+  // causes repeated cold starts and false release failures.
+  T.env.cacheDir = modelCache;
+  T.env.allowRemoteModels = !local;
+  return { local };
+}

package/kb/zip-extract.mjs

@@ -0,0 +1,297 @@
+// kb/zip-extract.mjs — extract a .zip using ONLY Node built-ins. No `unzip` binary, no shell.
+//
+// WHY THIS EXISTS (a real, measured stranger-machine failure, not a hypothetical):
+// The stranger-machine CI matrix (.github/workflows/stranger-matrix.yml) ran the PACKED installer on
+// a virgin windows-latest runner and the install aborted:
+//
+//   ✗ install stopped: extraction failed
+//     (`unzip -q -o D:\a\_temp\proj\node_modules\ruvnet-brain\dist\ruvnet-brain.zip
+//        -d D:\a\_temp\home-healthy\.cache\ruvnet-brain\kb` exited with code 1).
+//
+// Shelling out to `unzip` is fragile on Windows for two INDEPENDENT reasons, and a stranger hits
+// whichever one their machine hands them:
+//   1. PowerShell has no `unzip` at all — nothing named `unzip` is on a stock Windows PATH.
+//   2. Git Bash DOES put an MSYS2 `unzip` on PATH, and bin/install.mjs spawns with `shell: true` on
+//      Windows (it must, for .cmd shims), so the command line goes through cmd.exe carrying native
+//      `D:\a\...` paths into a POSIX-ish tool that treats `\` as an escape character. Same class of
+//      bug this repo already fixed once for ESM specifiers (raw `C:\` paths -> pathToFileURL).
+// A path handed to a shell must be correct for THAT shell. The most reliable way to get that right
+// is to never involve a shell: read the archive in-process.
+//
+// WHY NOT A LIBRARY: `npm ls --omit=dev --all` on this repo shows exactly two production deps
+// (@metaharness/flywheel, @metaharness/router) and NO zip library anywhere in the tree — measured,
+// not assumed. Node ships no archive reader either, so there was nothing already present to reuse:
+// adding yauzl/adm-zip/fflate would put a new third-party package (and its transitive tree) in the
+// path of `npx ruvnet-brain`, which bin/install.mjs's own header rule forbids ("dependency-free —
+// Node built-ins only"). node:zlib's inflateRawSync/createInflateRaw is the deflate half of a zip;
+// what is written below is only the container parsing around it.
+//
+// SCOPE, stated honestly: this reads the zip features our own bundles actually use — stored (0) and
+// deflate (8), ZIP64, data descriptors, unix modes, symlinks. It refuses, LOUDLY and by name,
+// anything it does not implement (encryption, other compression methods). It never guesses.
+//
+// FAIL LOUD. Every failure path throws an Error naming the archive, the entry, and what was wrong.
+// A silent partial extraction that leaves an empty directory behind is worse than the original bug,
+// so entry bytes are counted and (on Node >= 20.15 / 22.2, where zlib.crc32 exists) CRC-checked
+// against the archive's own central-directory values.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const SIG_EOCD = 0x06054b50;
+const SIG_EOCD64 = 0x06064b50;
+const SIG_EOCD64_LOC = 0x07064b50;
+const SIG_CENTRAL = 0x02014b50;
+const SIG_LOCAL = 0x04034b50;
+
+// zlib.crc32 landed in Node 20.15.0 / 22.2.0. package.json engines allow >=18, so it is OPTIONAL —
+// present it is used, absent the size check still stands and the caller is told which happened.
+// Reimplementing CRC-32 here would be hand-rolling something the runtime ships.
+const crc32 = typeof zlib.crc32 === 'function' ? zlib.crc32 : null;
+
+class Tally extends Transform {
+  constructor() { super(); this.bytes = 0; this.crc = 0; }
+  _transform(chunk, _enc, cb) {
+    this.bytes += chunk.length;
+    if (crc32) this.crc = crc32(chunk, this.crc);
+    this.push(chunk);
+    cb();
+  }
+}
+
+function readAt(fd, length, position) {
+  const buf = Buffer.allocUnsafe(length);
+  let got = 0;
+  while (got < length) {
+    const n = fs.readSync(fd, buf, got, length - got, position + got);
+    if (n === 0) break;
+    got += n;
+  }
+  if (got !== length) throw new Error(`truncated archive: wanted ${length} bytes at offset ${position}, got ${got}`);
+  return buf;
+}
+
+/** Locate the End Of Central Directory record, tolerating a trailing zip comment (<=64KB). */
+function findEocd(fd, size) {
+  const window = Math.min(size, 0xffff + 22);
+  const buf = readAt(fd, window, size - window);
+  for (let i = buf.length - 22; i >= 0; i--) {
+    if (buf.readUInt32LE(i) !== SIG_EOCD) continue;
+    return { buf, i, absolute: size - window + i };
+  }
+  throw new Error('not a zip archive (no End Of Central Directory record found)');
+}
+
+/**
+ * Where the central directory lives, honoring ZIP64 when the 32-bit fields are saturated.
+ * Bundles built by `zip -r` cross into ZIP64 on size or entry count without announcing it, so this
+ * is not optional defensive coding — a 4GB/65535-entry brain bundle is a realistic shape.
+ */
+function centralDirectoryLocation(fd, size) {
+  const { buf, i, absolute } = findEocd(fd, size);
+  let entries = buf.readUInt16LE(i + 10);
+  let cdSize = buf.readUInt32LE(i + 12);
+  let cdOffset = buf.readUInt32LE(i + 16);
+
+  if (entries === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) {
+    const locAt = absolute - 20;
+    if (locAt < 0) throw new Error('archive claims ZIP64 but has no ZIP64 locator');
+    const loc = readAt(fd, 20, locAt);
+    if (loc.readUInt32LE(0) !== SIG_EOCD64_LOC) throw new Error('archive claims ZIP64 but the ZIP64 locator signature is wrong');
+    const eocd64At = Number(loc.readBigUInt64LE(8));
+    const rec = readAt(fd, 56, eocd64At);
+    if (rec.readUInt32LE(0) !== SIG_EOCD64) throw new Error('ZIP64 End Of Central Directory signature is wrong');
+    entries = Number(rec.readBigUInt64LE(32));
+    cdSize = Number(rec.readBigUInt64LE(40));
+    cdOffset = Number(rec.readBigUInt64LE(48));
+  }
+  return { entries, cdSize, cdOffset };
+}
+
+/** ZIP64 extra field (0x0001): only the fields whose 32-bit form is saturated are present, in order. */
+function applyZip64Extra(extra, entry) {
+  let p = 0;
+  while (p + 4 <= extra.length) {
+    const id = extra.readUInt16LE(p);
+    const len = extra.readUInt16LE(p + 2);
+    const body = extra.subarray(p + 4, p + 4 + len);
+    if (id === 0x0001) {
+      let q = 0;
+      if (entry.uncompSize === 0xffffffff && q + 8 <= body.length) { entry.uncompSize = Number(body.readBigUInt64LE(q)); q += 8; }
+      if (entry.compSize === 0xffffffff && q + 8 <= body.length) { entry.compSize = Number(body.readBigUInt64LE(q)); q += 8; }
+      if (entry.localOffset === 0xffffffff && q + 8 <= body.length) { entry.localOffset = Number(body.readBigUInt64LE(q)); q += 8; }
+      return;
+    }
+    p += 4 + len;
+  }
+}
+
+function parseCentralDirectory(cd) {
+  const out = [];
+  let p = 0;
+  while (p + 46 <= cd.length) {
+    if (cd.readUInt32LE(p) !== SIG_CENTRAL) break;
+    const nameLen = cd.readUInt16LE(p + 28);
+    const extraLen = cd.readUInt16LE(p + 30);
+    const commentLen = cd.readUInt16LE(p + 32);
+    const entry = {
+      versionMadeBy: cd.readUInt16LE(p + 4),
+      flags: cd.readUInt16LE(p + 8),
+      method: cd.readUInt16LE(p + 10),
+      crc: cd.readUInt32LE(p + 16),
+      compSize: cd.readUInt32LE(p + 20),
+      uncompSize: cd.readUInt32LE(p + 24),
+      externalAttrs: cd.readUInt32LE(p + 38),
+      localOffset: cd.readUInt32LE(p + 42),
+      name: cd.subarray(p + 46, p + 46 + nameLen).toString('utf8'),
+    };
+    applyZip64Extra(cd.subarray(p + 46 + nameLen, p + 46 + nameLen + extraLen), entry);
+    out.push(entry);
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return out;
+}
+
+/**
+ * Reject anything that would write outside destDir. A downloaded archive is untrusted input, and
+ * `unzip` itself refuses `../` traversal — so this is parity with the tool being replaced, not an
+ * extra. Backslash is normalized to `/` first: a zip written on Windows may legitimately use it,
+ * and treating `a\..\..\b` as one opaque segment is exactly how traversal guards get bypassed.
+ */
+function safeJoin(destDir, name) {
+  const rel = name.replace(/\\/g, '/');
+  if (rel.startsWith('/') || /^[a-zA-Z]:/.test(rel)) return null;
+  if (rel.split('/').some((seg) => seg === '..')) return null;
+  const target = path.resolve(destDir, rel);
+  const root = path.resolve(destDir);
+  if (target !== root && !target.startsWith(root + path.sep)) return null;
+  return target;
+}
+
+/**
+ * Extract `zipPath` into `destDir`, overwriting existing files (idempotent — the `-o` of
+ * `unzip -q -o`). Returns { entries, files, bytes, crcChecked }.
+ * Throws an Error naming the archive and the offending entry on ANY problem.
+ */
+export async function extractZip(zipPath, destDir) {
+  const fd = fs.openSync(zipPath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    if (size === 0) throw new Error('archive is empty (0 bytes)');
+    const { cdSize, cdOffset } = centralDirectoryLocation(fd, size);
+    if (cdOffset + cdSize > size) throw new Error(`central directory runs past end of file (offset ${cdOffset} + ${cdSize} > ${size})`);
+    const entries = parseCentralDirectory(readAt(fd, cdSize, cdOffset));
+    if (entries.length === 0) throw new Error('central directory contains no entries');
+
+    fs.mkdirSync(destDir, { recursive: true });
+    let files = 0;
+    let bytes = 0;
+
+    const normalizedEntryNames = entries.map((entry) => entry.name.replace(/\\/g, '/'));
+    for (let entryIndex = 0; entryIndex < entries.length; entryIndex++) {
+      const e = entries[entryIndex];
+      if (e.flags & 0x1) throw new Error(`entry "${e.name}" is encrypted — this archive cannot be extracted without a password`);
+      const target = safeJoin(destDir, e.name);
+      if (target === null) throw new Error(`entry "${e.name}" would escape the destination directory — refusing to extract (possible zip-slip)`);
+
+      // PowerShell Compress-Archive can encode directories without a trailing slash and marks them
+      // inconsistently across PowerShell/.NET versions: some archives carry the DOS directory bit,
+      // while others carry neither that bit nor a trailing slash. A zero-byte entry that is an
+      // ancestor of another central-directory entry is unambiguously a directory, so use the
+      // archive's own tree as the final signal. Treating it as a file poisons the next nested entry
+      // (`vendor` file, then `vendor/package.json` → ENOTDIR).
+      const unixType = (e.externalAttrs >>> 16) & 0xf000;
+      const normalizedName = normalizedEntryNames[entryIndex].replace(/\/+$/, '');
+      const hasDescendant = e.uncompSize === 0 && normalizedEntryNames.some(
+        (candidate, candidateIndex) => candidateIndex !== entryIndex
+          && candidate.startsWith(`${normalizedName}/`),
+      );
+      const isDirectory = e.name.endsWith('/')
+        || (e.externalAttrs & 0x10) !== 0
+        || ((e.versionMadeBy >> 8) === 3 && unixType === 0x4000)
+        || hasDescendant;
+      if (isDirectory) {
+        try {
+          if (fs.existsSync(target) && !fs.lstatSync(target).isDirectory()) {
+            fs.rmSync(target, { recursive: true, force: true });
+          }
+        } catch { /* mkdir below reports any unrecoverable collision with the exact path */ }
+        fs.mkdirSync(target, { recursive: true });
+        continue;
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+
+      // Sizes/offsets come from the CENTRAL directory, never the local header: with a data
+      // descriptor (flag bit 3, what streaming zippers emit) the local header's sizes are zeros.
+      const local = readAt(fd, 30, e.localOffset);
+      if (local.readUInt32LE(0) !== SIG_LOCAL) throw new Error(`entry "${e.name}" has a bad local header signature at offset ${e.localOffset}`);
+      const dataStart = e.localOffset + 30 + local.readUInt16LE(26) + local.readUInt16LE(28);
+
+      if (e.method !== 0 && e.method !== 8) {
+        throw new Error(`entry "${e.name}" uses unsupported compression method ${e.method} (only stored=0 and deflate=8 are implemented)`);
+      }
+
+      const isSymlink = (e.versionMadeBy >> 8) === 3 && ((e.externalAttrs >>> 16) & 0xf000) === 0xa000;
+      if (isSymlink) {
+        // A symlink's payload is its target path — always tiny, so it is read whole rather than streamed.
+        const comp = e.compSize === 0 ? Buffer.alloc(0) : readAt(fd, e.compSize, dataStart);
+        const linkTarget = (e.method === 8 ? zlib.inflateRawSync(comp) : comp).toString('utf8');
+        fs.rmSync(target, { recursive: true, force: true });
+        fs.symlinkSync(linkTarget, target);
+        files++;
+        continue;
+      }
+
+      // A zero-length entry has no data range to stream (start > end would be a nonsense read), so
+      // it is written directly. Its size/CRC assertions below still apply.
+      if (e.compSize === 0) {
+        fs.writeFileSync(target, Buffer.alloc(0));
+        if (e.uncompSize !== 0) throw new Error(`entry "${e.name}" is corrupt: 0 compressed bytes but claims ${e.uncompSize} uncompressed`);
+        files++;
+        continue;
+      }
+
+      const tally = new Tally();
+      const stages = [fs.createReadStream(zipPath, { start: dataStart, end: dataStart + e.compSize - 1 })];
+      if (e.method === 8) stages.push(zlib.createInflateRaw());
+      stages.push(tally, fs.createWriteStream(target));
+
+      try {
+        await pipeline(...stages);
+      } catch (err) {
+        throw new Error(`entry "${e.name}" failed to inflate (${err && err.code ? err.code : ''}${err && err.message ? ` ${err.message}` : ''}) — the archive is corrupt or truncated`);
+      }
+      if (tally.bytes !== e.uncompSize) {
+        throw new Error(`entry "${e.name}" is corrupt: expected ${e.uncompSize} bytes, extracted ${tally.bytes}`);
+      }
+      if (crc32 && (tally.crc >>> 0) !== (e.crc >>> 0)) {
+        // Zero-padded to 8 hex digits so the value is directly comparable to the one Info-ZIP's
+        // own `unzip` prints for the same damaged entry ("bad CRC 811e0dd1 (should be 0f6994e4)").
+        const hex = (n) => (n >>> 0).toString(16).padStart(8, '0');
+        throw new Error(`entry "${e.name}" failed its CRC-32 check (expected ${hex(e.crc)}, got ${hex(tally.crc)}) — the archive is corrupt`);
+      }
+
+      // Unix permission bits, when the archive carries them. Skipped on Windows, which has no
+      // POSIX mode and where chmod is a no-op at best.
+      if (process.platform !== 'win32' && (e.versionMadeBy >> 8) === 3) {
+        const mode = (e.externalAttrs >>> 16) & 0o7777;
+        if (mode) { try { fs.chmodSync(target, mode); } catch { /* mode is a nicety, not the payload */ } }
+      }
+      files++;
+      bytes += tally.bytes;
+    }
+    return { entries: entries.length, files, bytes, crcChecked: Boolean(crc32) };
+  } catch (err) {
+    // Always name the archive: "extraction failed" without the file is the message this whole
+    // change exists to stop shipping.
+    err.message = `${zipPath}: ${err.message}`;
+    throw err;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+export default { extractZip };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "version": "3.9.84-dev",
-  "description": "One-command installer for RuvNet Brain \u2014 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.",
+  "version": "3.9.129-dev",
+  "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": {
     "ruvnet-brain": "bin/install.mjs"
@@ -10,11 +10,15 @@
     "test": "node plugin/test/run-tests.mjs",
     "version:check": "node scripts/sync-version.mjs --check",
     "claims:verify": "node scripts/claims-verify.mjs",
+    "claims:fix": "node scripts/claims-verify.mjs --fix",
     "version:sync": "node scripts/sync-version.mjs",
     "test:unit": "vitest run tests/unit",
+    "test:mesh": "vitest run tests/mesh",
+    "test:mutation": "vitest run tests/mutation",
+    "test:regression": "vitest run tests/regression",
     "qe:ux": "node scripts/qe/ux-suite.mjs",
     "test:cov": "vitest run tests/unit --coverage",
-    "test:all": "npm run test:unit && npm run test:integration && npm test",
+    "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",
@@ -23,6 +27,8 @@
     "eval": "node scripts/eval-brain.mjs",
     "eval:gate": "node scripts/eval-brain.mjs --gate",
     "eval:record": "node scripts/eval-brain.mjs --record",
+    "eval:top100:build": "node scripts/top100-corpus.mjs",
+    "eval:top100": "node scripts/top100-benchmark.mjs",
     "gists:index": "node scripts/ingest-gists.mjs --index-only",
     "gists:sync": "node scripts/ingest-gists.mjs && node kb/forge-big.mjs both --dir kb --name ruv-gists",
     "test:integration": "vitest run tests/integration",
@@ -31,28 +37,48 @@
     "catalog:refresh": "node scripts/refresh-model-catalog.mjs",
     "falsify": "node scripts/falsify.mjs",
     "sbom": "npx --yes @cyclonedx/cyclonedx-npm --omit dev --output-file sbom/ruvnet-brain.cdx.json --mc-type application --validate",
+    "learning:replay": "node scripts/learning-replay.mjs",
+    "learning:replay:check": "node scripts/learning-replay.mjs --check-portfolio",
+    "learning:replay:mutants:check": "node scripts/learning-replay.mjs --check-mutants",
+    "learning:replay:dry": "node scripts/learning-replay.mjs --dry-run",
     "wired:check": "node scripts/wired-check.mjs --check",
     "doc:currency": "node scripts/doc-currency.mjs --check",
-    "status:check": "node scripts/status-honesty.mjs"
+    "status:check": "node scripts/status-honesty.mjs",
+    "cap:collect": "node scripts/rerank-cap-eval.mjs --collect",
+    "cap:report": "node scripts/rerank-cap-eval.mjs --report",
+    "cap:ab": "node scripts/rerank-cap-warm-ab.mjs"
   },
   "files": [
     "bin/install.mjs",
+    "plugin/mcp/managed-cli-interface.mjs",
     "plugin/mcp/server.mjs",
+    "plugin/scripts/codex-hook-wrapper.mjs",
     "!plugin/README.md",
     "README.md",
     "LICENSE",
     "config/model-router/",
     "kb/verify-citation.mjs",
+    "kb/zip-extract.mjs",
+    "kb/brain-profile.mjs",
+    "kb/model-requirements.mjs",
     "scripts/model-router-engine.mjs",
     "scripts/model-router-setup.mjs",
     "scripts/model-router-status.mjs",
     "scripts/model-router-outcome.mjs",
+    "scripts/subscription-hosts.mjs",
+    "scripts/dual-host-deliberation.mjs",
+    "scripts/dual-host-suggest.mjs",
     "scripts/route-cheap.mjs",
     "scripts/dispatch-receipt.mjs",
     "scripts/metaharness-receipts.mjs",
     "scripts/codex-routed.sh",
     "scripts/metaharness-router.mjs",
     "scripts/no-silent-substitution.mjs",
+    "scripts/user-settings.mjs",
+    "scripts/selfcheck.mjs",
+    "scripts/hook-registry.mjs",
+    "scripts/install-scope.mjs",
+    "scripts/upgrade-notice.mjs",
     "scripts/falsify.mjs",
     "scripts/nightly-watchdog.mjs",
     "scripts/job-heartbeat.sh"
@@ -83,7 +109,9 @@
   "author": "Stuart Kerr",
   "devDependencies": {
     "@metaharness/darwin": "~0.8.0",
+    "@ruvector/rvf": "^0.3.4",
     "@vitest/coverage-v8": "^4.1.10",
+    "playwright": "^1.62.0",
     "vitest": "^4.1.10"
   },
   "dependencies": {