ruvnet-brain 4.4.1 → 4.5.0

package/scripts/oracle/doc2query-reach.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/doc2query-reach.mjs — ADR-099 arm A, measurement: do generated entry points bring
+ * the gold file into the pool?
+ *
+ * Builds one RVF "entry" index per store from doc2query-generate output (every question embedded with
+ * the production query embedder, so a newcomer's question is matched question-to-question), then, for
+ * every need, asks the gold store's entry index for its top --k questions and collapses them to files.
+ * Pool reach is reported against the existing pool (dense 64 + keyword lane, from an abstain-trace
+ * run's poolRanks), on the TRAIN and HELD-OUT splits separately, with Wilson intervals:
+ *   baselineReach  gold already pooled by dense + keyword
+ *   entryReach     gold among the entry lane's files
+ *   unionReach     either
+ * Restricted to needs whose gold repository the router searched (the trace's eligible set); over all
+ * needs only entryReach is reported (store-level, independent of routing).
+ *
+ *   node scripts/oracle/doc2query-reach.mjs --runtime <kbDir with forge-ask.mjs + node_modules>
+ *     --d2q <generated.jsonl> --set <need-set.json> --split <split.json> --trace <abstain-trace.json>
+ *     [--k 24] [--files 8] [--index-dir <dir>] [--out <file>]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { wilson } from '../eval-brain.mjs';
+
+/** Collapse ranked entry hits (each pointing at a file) to the first `files` distinct files. */
+export function filesFromEntries(hits, pathOfId, files) {
+  const out = [];
+  for (const h of hits) {
+    const p = pathOfId(h.id);
+    if (p && !out.includes(p)) out.push(p);
+    if (out.length >= files) break;
+  }
+  return out;
+}
+
+export function reachSummary(rows) {
+  const r = (pred) => { const k = rows.filter(pred).length; const w = wilson(k, rows.length); return { k, n: rows.length, lo: +w.lo.toFixed(4), hi: +w.hi.toFixed(4) }; };
+  return { baselineReach: r((x) => x.baseline), entryReach: r((x) => x.entry), unionReach: r((x) => x.baseline || x.entry),
+    gained: rows.filter((x) => x.entry && !x.baseline).length };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+  const runtime = path.resolve(arg('--runtime'));
+  const { __embedInternals } = await import(pathToFileURL(path.join(runtime, 'forge-ask.mjs')).href);
+  const { loadRvf } = await import(pathToFileURL(path.join(runtime, 'resolve-deps.mjs')).href);
+  const { RvfDatabase } = loadRvf().mod;
+  const embed = __embedInternals.embed;
+  const k = Number(arg('--k', 24));
+  const nFiles = Number(arg('--files', 8));
+  const indexDir = arg('--index-dir', fs.mkdtempSync(path.join(runtime, '..', 'd2q-index-')));
+  fs.mkdirSync(indexDir, { recursive: true });
+  const gen = fs.readFileSync(arg('--d2q'), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  const stores = [...new Set(gen.map((g) => g.store))];
+  const indexes = new Map();
+  // The entry index uses the store's own query embedder (big variant when present: bge + query prefix),
+  // exactly what searchKb computes for the question, so production needs one query embedding.
+  const cfgFor = (store) => {
+    for (const v of [`${store}.big.rvf.embed.json`, `${store}.rvf.embed.json`]) {
+      try { return JSON.parse(fs.readFileSync(path.join(runtime, v), 'utf8')); } catch { /* next */ }
+    }
+    return undefined;
+  };
+  for (const store of stores) {
+    const cfg = cfgFor(store);
+    const dims = cfg?.dimensions || 384;
+    const rows = gen.filter((g) => g.store === store).flatMap((g) => g.questions.map((q) => ({ q, path: g.path })));
+    const file = path.join(indexDir, `${store}.entry.rvf`);
+    fs.rmSync(file, { force: true });
+    const db = await RvfDatabase.create(file, { dimensions: dims, metric: 'cosine' });
+    const batch = [];
+    for (let i = 0; i < rows.length; i++) {
+      batch.push({ id: i + 1, vector: Array.from(await embed(rows[i].q, cfg)) });
+      if (batch.length === 64 || i === rows.length - 1) { await db.ingestBatch(batch.splice(0)); }
+      if (i % 500 === 0) process.stderr.write(`\r[d2q-reach] ${store} ${i}/${rows.length}`);
+    }
+    indexes.set(store, { db, cfg, paths: rows.map((r) => r.path), questions: rows.length, model: cfg?.model || 'default' });
+  }
+  const set = JSON.parse(fs.readFileSync(arg('--set'), 'utf8')).questions;
+  const split = JSON.parse(fs.readFileSync(arg('--split'), 'utf8'));
+  const trace = JSON.parse(fs.readFileSync(arg('--trace'), 'utf8'));
+  const pooled = new Map(trace.poolRanks.map((p) => [p.id, p.poolRank != null]));
+  const rows = [];
+  for (const q of set) {
+    const store = q.repo.toLowerCase();
+    const idx = indexes.get(store);
+    if (!idx) continue;
+    const hits = await idx.db.query(Array.from(await embed(q.need, idx.cfg)), k);
+    const files = filesFromEntries(hits, (id) => idx.paths[Number(id) - 1], nFiles);
+    rows.push({ id: q.id, split: split.train.includes(q.id) ? 'train' : 'heldout', routed: pooled.has(q.id),
+      baseline: pooled.get(q.id) === true, entry: files.includes(q.path), entryRank: files.indexOf(q.path) + 1 || null });
+  }
+  const report = { kind: 'ruvnet-brain-doc2query-reach', k, files: nFiles,
+    indexes: Object.fromEntries([...indexes].map(([s, v]) => [s, { questions: v.questions, model: v.model }])),
+    generatedFiles: gen.length, keptQuestions: gen.reduce((s, g) => s + g.questions.length, 0),
+    rejectedQuestions: gen.reduce((s, g) => s + (g.rejected?.length || 0), 0), results: {} };
+  for (const sp of ['train', 'heldout']) {
+    report.results[sp] = { routedNeeds: reachSummary(rows.filter((r) => r.split === sp && r.routed)),
+      // the trace covers only routed needs, so over all needs only the entry lane itself is known
+      allNeedsEntryReach: reachSummary(rows.filter((r) => r.split === sp)).entryReach };
+  }
+  report.rows = rows;
+  if (arg('--out')) fs.writeFileSync(arg('--out'), `${JSON.stringify(report, null, 1)}\n`);
+  console.log(JSON.stringify({ ...report, rows: undefined }, null, 1));
+  process.exit(0);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/oracle/judge-train.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/judge-train.mjs — fit the learned judge (kb/judge-rank.mjs, ADR-099 arm C) on the
+ * need-set TRAIN split and report it on the HELD-OUT split, offline.
+ *
+ * Input is the scored pool the search already recorded (KB_CE_TRACE: one line per question, every
+ * pooled candidate with its cross-encoder logit, dense distance, lane, title, path and length), so
+ * training and evaluation replay exactly what the cross-encoder saw; no model is run here.
+ *
+ * Model: logistic regression over JUDGE_FEATURES, standardised on train, L2 1.0, class-balanced,
+ * full-batch gradient descent (deterministic). Positive = the candidate is the gold file or a
+ * pre-registered alternative. Operating point: the smallest threshold on the judge's top score at
+ * which TRAIN precision of answered questions reaches --precision (default 0.8); it is folded into
+ * the bias so the product's existing "score < 0 abstains" rule applies unchanged.
+ *
+ *   node scripts/oracle/judge-train.mjs --set <need-set.json> --split <split.json> --trace <cetrace.jsonl>
+ *     [--precision 0.8] [--weights <out.json>] [--report <out.json>]
+ *     [--recall-trace <recall.cetrace.jsonl> --recall-fixture data/retrieval-query-evidence.json]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { wilson } from '../eval-brain.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const { JUDGE_FEATURES, judgeFeatures, judgeLogit } = await import(pathToFileURL(path.join(ROOT, 'kb/judge-rank.mjs')).href);
+
+const norm = (p) => String(p || '').replace(/^\.\//, '');
+export function isTarget(q, cand) {
+  const targets = [{ repo: q.repo, path: q.path }, ...(q.alternatives || [])];
+  return targets.some((t) => String(t.repo).toLowerCase() === String(cand.repo).toLowerCase() && norm(t.path) === norm(cand.path));
+}
+
+/** Map need id -> its last recorded pool, from KB_CE_TRACE lines (unparsable lines are skipped). */
+export function poolsByNeed(questions, traceText) {
+  const byNeed = new Map(questions.map((q) => [q.need, q.id]));
+  const pools = new Map();
+  for (const line of traceText.split('\n')) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    const id = byNeed.get(row.query);
+    if (id && Array.isArray(row.cands) && row.cands.length) pools.set(id, row.cands);
+  }
+  return pools;
+}
+
+export function fitLogistic(X, y, { l2 = 1, iters = 3000, lr = 0.1 } = {}) {
+  const d = X[0].length;
+  const mean = Array.from({ length: d }, (_, j) => X.reduce((s, x) => s + x[j], 0) / X.length);
+  const std = Array.from({ length: d }, (_, j) => Math.sqrt(X.reduce((s, x) => s + (x[j] - mean[j]) ** 2, 0) / X.length) || 1);
+  const Z = X.map((x) => x.map((v, j) => (v - mean[j]) / std[j]));
+  const pos = y.filter(Boolean).length;
+  const wPos = pos ? (y.length - pos) / pos : 1;
+  const w = new Array(d).fill(0);
+  let b = 0;
+  for (let it = 0; it < iters; it++) {
+    const g = new Array(d).fill(0);
+    let gb = 0;
+    let W = 0;
+    for (let i = 0; i < Z.length; i++) {
+      const s = b + Z[i].reduce((a, v, j) => a + v * w[j], 0);
+      const p = 1 / (1 + Math.exp(-s));
+      const cw = y[i] ? wPos : 1;
+      const e = cw * (p - (y[i] ? 1 : 0));
+      for (let j = 0; j < d; j++) g[j] += e * Z[i][j];
+      gb += e;
+      W += cw;
+    }
+    for (let j = 0; j < d; j++) w[j] -= lr * (g[j] / W + (l2 * w[j]) / Z.length);
+    b -= lr * (gb / W);
+  }
+  return { weights: w, bias: b, mean, std };
+}
+
+/** Per question: the top candidate under a scorer, whether a target is in the top 1 / top 5, top score. */
+export function decide(questions, pools, score) {
+  return questions.filter((q) => pools.has(q.id)).map((q) => {
+    const cands = pools.get(q.id);
+    const s = score(q, cands);
+    const order = s.map((v, i) => [v, i]).sort((a, b) => b[0] - a[0]).map(([, i]) => i);
+    return { id: q.id, top: s[order[0]], at1: isTarget(q, cands[order[0]]),
+      within5: order.slice(0, 5).some((i) => isTarget(q, cands[i])) };
+  });
+}
+
+export function metrics(rows, n, threshold = 0) {
+  const r = (k, m) => { const w = wilson(k, m); return { k, n: m, lo: +w.lo.toFixed(4), hi: +w.hi.toFixed(4) }; };
+  const answered = rows.filter((x) => x.top >= threshold);
+  return {
+    traced: rows.length,
+    goldWithin5: r(rows.filter((x) => x.within5).length, n),
+    goldAt1: r(rows.filter((x) => x.at1).length, n),
+    // measure-need-set's definitions (target within 5 AND not abstained), so baselines compare
+    confidentHit: r(answered.filter((x) => x.within5).length, n),
+    confidentWrong: r(answered.filter((x) => !x.within5).length, n),
+    // the stricter reading: the single top answer is the target
+    confidentHitTop1: r(answered.filter((x) => x.at1).length, n),
+    abstained: r(n - answered.length, n),
+    precision: r(answered.filter((x) => x.at1).length, answered.length),
+  };
+}
+
+export function chooseThreshold(rows, precision) {
+  const tops = [...new Set(rows.map((x) => x.top))].sort((a, b) => a - b);
+  for (const t of tops) {
+    const ans = rows.filter((x) => x.top >= t);
+    if (ans.length && ans.filter((x) => x.at1).length / ans.length >= precision) return t;
+  }
+  return Infinity;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+  const set = JSON.parse(fs.readFileSync(arg('--set'), 'utf8')).questions;
+  const split = JSON.parse(fs.readFileSync(arg('--split'), 'utf8'));
+  const pools = poolsByNeed(set, fs.readFileSync(arg('--trace'), 'utf8'));
+  const train = set.filter((q) => split.train.includes(q.id));
+  const held = set.filter((q) => split.heldout.includes(q.id));
+  const X = [];
+  const y = [];
+  for (const q of train) {
+    if (!pools.has(q.id)) continue;
+    const cands = pools.get(q.id);
+    judgeFeatures(q.need, cands).forEach((x, i) => { X.push(x); y.push(isTarget(q, cands[i])); });
+  }
+  const fit = fitLogistic(X, y);
+  const model0 = { ...fit, features: JUDGE_FEATURES };
+  const judgeScore = (m) => (q, cands) => judgeFeatures(q.need, cands).map((x) => judgeLogit(m, x));
+  const ceScore = (q, cands) => cands.map((c) => (typeof c.ce === 'number' ? c.ce : -Infinity));
+  const precision = Number(arg('--precision', 0.8));
+  const tau = chooseThreshold(decide(train, pools, judgeScore(model0)), precision);
+  const model = { ...model0, bias: Number.isFinite(tau) ? fit.bias - tau : -1e9, threshold: tau,
+    trainedOn: { split: split.salt, trainNeeds: train.length, tracedTrain: train.filter((q) => pools.has(q.id)).length,
+      candidates: X.length, positives: y.filter(Boolean).length, precisionTarget: precision } };
+  const report = {
+    kind: 'ruvnet-brain-judge-report', features: JUDGE_FEATURES, trainedOn: model.trainedOn, threshold: tau,
+    weights: Object.fromEntries(JUDGE_FEATURES.map((f, j) => [f, +model.weights[j].toFixed(4)])),
+    train: { crossEncoder: metrics(decide(train, pools, ceScore), train.length), judge: metrics(decide(train, pools, judgeScore(model)), train.length) },
+    heldout: { crossEncoder: metrics(decide(held, pools, ceScore), held.length), judge: metrics(decide(held, pools, judgeScore(model)), held.length) },
+  };
+  // Offline replay on the recall-gate fixture's recorded pools: does re-ranking hurt questions the
+  // cross-encoder already answers? (Approximate: selectResults' name boosts are not replayed here, so
+  // the full path is the authority; this only flags gross damage early.)
+  if (arg('--recall-trace') && arg('--recall-fixture')) {
+    const fx = JSON.parse(fs.readFileSync(arg('--recall-fixture'), 'utf8')).queries;
+    const items = Object.entries(fx).map(([store, v]) => ({ id: store, need: v.query, repo: store, path: v.expected.path }));
+    const rpools = poolsByNeed(items, fs.readFileSync(arg('--recall-trace'), 'utf8'));
+    report.recallReplay = { crossEncoder: metrics(decide(items, rpools, ceScore), items.length),
+      judge: metrics(decide(items, rpools, judgeScore(model)), items.length) };
+  }
+  if (arg('--weights')) fs.writeFileSync(arg('--weights'), `${JSON.stringify(model, null, 1)}\n`);
+  if (arg('--report')) fs.writeFileSync(arg('--report'), `${JSON.stringify(report, null, 1)}\n`);
+  console.log(JSON.stringify({ threshold: tau, trainedOn: model.trainedOn, heldout: report.heldout }, null, 1));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/oracle/need-set-split.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/need-set-split.mjs — a frozen, stratified train / held-out split of a need set.
+ *
+ * Anything that LEARNS from novice needs (a query adapter, a learned abstain model) may train only
+ * on `train`; every claim about it is measured on `heldout`. The split is a pure function of the
+ * question ids and a salt: within each repository the ids are ordered by sha256(salt + id) and the
+ * first round(n * trainFraction) go to train. Re-running it on the same set yields the same split.
+ *
+ *   node scripts/oracle/need-set-split.mjs --set <need-set.json> [--salt v1] [--train 0.5] [--out <file>]
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function splitNeedSet(questions, { salt = 'v1', trainFraction = 0.5 } = {}) {
+  const byRepo = new Map();
+  for (const q of questions) {
+    if (!byRepo.has(q.repo)) byRepo.set(q.repo, []);
+    byRepo.get(q.repo).push(q.id);
+  }
+  const train = [];
+  const heldout = [];
+  for (const repo of [...byRepo.keys()].sort()) {
+    const ids = byRepo.get(repo)
+      .map((id) => ({ id, h: createHash('sha256').update(`${salt}\n${id}`).digest('hex') }))
+      .sort((a, b) => (a.h < b.h ? -1 : a.h > b.h ? 1 : 0))
+      .map((x) => x.id);
+    const cut = Math.round(ids.length * trainFraction);
+    train.push(...ids.slice(0, cut));
+    heldout.push(...ids.slice(cut));
+  }
+  return { salt, trainFraction, train, heldout };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+  const set = JSON.parse(fs.readFileSync(arg('--set'), 'utf8'));
+  const split = splitNeedSet(set.questions, { salt: arg('--salt', 'v1'), trainFraction: Number(arg('--train', 0.5)) });
+  const out = { kind: 'ruvnet-brain-need-set-split', set: { kind: set.kind, version: set.version, n: set.questions.length,
+    contentHash: set.contentHash }, ...split };
+  if (arg('--out')) fs.writeFileSync(arg('--out'), `${JSON.stringify(out, null, 1)}\n`);
+  console.log(JSON.stringify({ train: split.train.length, heldout: split.heldout.length, contentHash: set.contentHash }));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/oracle/sona-query-adapter-eval.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/sona-query-adapter-eval.mjs — ADR-099 arm B, an EXPERIMENT: can a SONA MicroLoRA
+ * query adapter (@ruvector/sona, rank 1-2) move a novice question's embedding so the gold file ranks
+ * higher in the store's own dense index?
+ *
+ * Train (need-set TRAIN split only): one SONA trajectory per need, beginning at the question's
+ * embedding, with one step whose activation is the gold passage's embedding (reward 1) and one step
+ * per top dense non-gold passage (reward 0), ended with quality 1. SONA's REINFORCE gradient
+ * ((reward - baseline) x activation, ruvector/crates/sona/src/types.rs) then pushes the adapter toward
+ * the gold direction. forceLearn() applies it.
+ * Evaluate (HELD-OUT, and TRAIN for fit): the gold file's rank among the store's top --depth dense
+ * hits for the raw question vs applyMicroLora(question); and the same on the recall-gate fixture, which
+ * the adapter must not hurt. An untrained adapter is measured too, because it is not the identity.
+ *
+ *   node scripts/oracle/sona-query-adapter-eval.mjs --kb <kbDir with forge-ask.mjs + node_modules>
+ *     --sona <dir containing node_modules/@ruvector/sona> --set <need-set.json> --split <split.json>
+ *     [--recall data/retrieval-query-evidence.json] [--depth 64] [--negatives 4] [--out <file>]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { wilson } from '../eval-brain.mjs';
+
+/** Rank (1-based) of the first hit whose path is `gold`, or null within the list. */
+export function rankOf(paths, gold) {
+  const i = paths.indexOf(gold);
+  return i < 0 ? null : i + 1;
+}
+
+/** Paired comparison of two rank lists (null = not within depth). */
+export function compareRanks(base, adapted, cut = 5) {
+  const within = (r) => r != null && r <= cut;
+  const n = base.length;
+  const r = (k) => { const w = wilson(k, n); return { k, n, lo: +w.lo.toFixed(4), hi: +w.hi.toFixed(4) }; };
+  let gained = 0;
+  let lost = 0;
+  for (let i = 0; i < n; i++) {
+    if (!within(base[i]) && within(adapted[i])) gained++;
+    if (within(base[i]) && !within(adapted[i])) lost++;
+  }
+  return { base: r(base.filter(within).length), adapted: r(adapted.filter(within).length), gained, lost,
+    inDepthBase: base.filter((x) => x != null).length, inDepthAdapted: adapted.filter((x) => x != null).length };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+  const kb = path.resolve(arg('--kb'));
+  const depth = Number(arg('--depth', 64));
+  const negatives = Number(arg('--negatives', 4));
+  const require = createRequire(path.join(path.resolve(arg('--sona')), 'index.js'));
+  const { SonaEngine } = require('@ruvector/sona');
+  const { __embedInternals } = await import(pathToFileURL(path.join(kb, 'forge-ask.mjs')).href);
+  const { loadRvf } = await import(pathToFileURL(path.join(kb, 'resolve-deps.mjs')).href);
+  const { RvfDatabase } = loadRvf().mod;
+  const embed = __embedInternals.embed;
+  const set = JSON.parse(fs.readFileSync(arg('--set'), 'utf8')).questions;
+  const split = JSON.parse(fs.readFileSync(arg('--split'), 'utf8'));
+  const stores = new Map();
+  const storeOf = async (name) => {
+    if (stores.has(name)) return stores.get(name);
+    const big = fs.existsSync(path.join(kb, `${name}.big.rvf`));
+    const base = path.join(kb, big ? `${name}.big.rvf` : `${name}.rvf`);
+    const cfg = JSON.parse(fs.readFileSync(`${base}.embed.json`, 'utf8'));
+    const idmap = JSON.parse(fs.readFileSync(`${base}.idmap.json`, 'utf8')).idToLabel;
+    const labelToId = new Map(Object.entries(idmap).map(([id, label]) => [Number(label), id]));
+    const passages = path.join(kb, big && fs.existsSync(path.join(kb, `${name}.big.passages.jsonl`)) ? `${name}.big.passages.jsonl` : `${name}.passages.jsonl`);
+    const pathOf = new Map();
+    const textOf = new Map();
+    for (const l of fs.readFileSync(passages, 'utf8').split('\n')) {
+      if (!l) continue;
+      const r = JSON.parse(l);
+      pathOf.set(String(r.id), r.path);
+      if (!textOf.has(r.path)) textOf.set(r.path, String(r.text || ''));
+    }
+    const db = await RvfDatabase.openReadonly(base);
+    const s = { name, cfg, db, labelToId, pathOf, textOf, engine: new SonaEngine(cfg.dimensions) };
+    stores.set(name, s);
+    return s;
+  };
+  const search = async (s, vec) => {
+    const hits = await s.db.query(Array.from(vec), depth);
+    const paths = [];
+    for (const h of hits) {
+      const p = s.pathOf.get(String(s.labelToId.get(Number(h.id)) ?? h.id));
+      if (p && !paths.includes(p)) paths.push(p);
+    }
+    return paths;
+  };
+  const passageEmbed = (s, text) => embed(text, { ...s.cfg, queryPrefix: '' });
+  const qs = set.map((q) => ({ ...q, store: q.repo.toLowerCase(), isTrain: split.train.includes(q.id) }));
+  // TRAIN
+  let trained = 0;
+  for (const q of qs.filter((x) => x.isTrain)) {
+    const s = await storeOf(q.store);
+    const qv = Array.from(await embed(q.need, s.cfg));
+    const gold = s.textOf.get(q.path);
+    if (!gold) continue;
+    const t = s.engine.beginTrajectory(qv);
+    const zeros = new Array(64).fill(0);
+    s.engine.addTrajectoryStep(t, Array.from(await passageEmbed(s, q.span || gold)), zeros, 1);
+    for (const p of (await search(s, qv)).filter((p) => p !== q.path).slice(0, negatives)) {
+      s.engine.addTrajectoryStep(t, Array.from(await passageEmbed(s, s.textOf.get(p) || '')), zeros, 0);
+    }
+    s.engine.endTrajectory(t, 1);
+    trained++;
+    process.stderr.write(`\r[sona-eval] trained ${trained}`);
+  }
+  const learn = {};
+  for (const s of stores.values()) learn[s.name] = String(s.engine.forceLearn());
+  // EVALUATE: raw vs adapted, on held-out and train needs, and on the recall fixture
+  const evalSet = async (items) => {
+    const base = [];
+    const adapted = [];
+    for (const it of items) {
+      const s = await storeOf(it.store);
+      const qv = Array.from(await embed(it.query, s.cfg));
+      base.push(rankOf(await search(s, qv), it.gold));
+      adapted.push(rankOf(await search(s, s.engine.applyMicroLora(qv)), it.gold));
+    }
+    return compareRanks(base, adapted);
+  };
+  const needItems = (isTrain) => qs.filter((q) => q.isTrain === isTrain).map((q) => ({ store: q.store, query: q.need, gold: q.path }));
+  const report = { kind: 'ruvnet-brain-sona-query-adapter-eval', depth, negatives, trained, learn,
+    heldout: await evalSet(needItems(false)), train: await evalSet(needItems(true)) };
+  if (arg('--recall')) {
+    const fx = JSON.parse(fs.readFileSync(arg('--recall'), 'utf8')).queries;
+    const items = Object.entries(fx).filter(([store]) => stores.has(store))
+      .map(([store, v]) => ({ store, query: v.query, gold: v.expected.path }));
+    report.recallFixtureSameStores = await evalSet(items);
+  }
+  if (arg('--out')) fs.writeFileSync(arg('--out'), `${JSON.stringify(report, null, 1)}\n`);
+  console.log(JSON.stringify(report, null, 1));
+  process.exit(0);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();