pi-supernova 0.0.8 → 0.0.15

package/evidence.js

@@ -0,0 +1,429 @@
+import * as path from "node:path";
+import { WorkspaceIndex } from "./repo-index.js";
+import { tokenizeQuery, scorePathTopology } from "./snap.js";
+import { isTestPath } from "./workspace.js";
+
+// Zero-token evidence selection over source code, after Zero-Mem (arXiv:2607.29377).
+// The codebase is the interaction history H; declared spans are the context units;
+// identifiers are the entities. Every step below is deterministic (no model call)
+// and every returned unit carries provenance (path, lines) back to the raw source.
+//
+//   eq.3  G = (Vd ∪ Ve, Ede ∪ Edd)         span/identifier nodes, co-occurrence + adjacency edges
+//   eq.4  w(d,e) = c(e,d) / Σ_e' c(e',d)    entity–span weight
+//   eq.5  T(H) = file ∪ span ∪ line ∪ local  granularities
+//   eq.6  ϕ(q) = {subject, keywords, type, temporal, boundary}
+//   eq.7  Route(q) ∈ {relational, local}      → primary view weight ρ
+//   eq.8  η0(e|q) = sim(e, ê)                 lexical alignment (no encoder)
+//   eq.9  η1(e') = Σ_e η0(e) Σ_{z ∈ Z(e)∩Z(e')} sim(q, z)
+//   eq.10 π = (1−γ) r + γ Pᵀ π               personalized PageRank over spans
+//   eq.11 file → span → line                 coarse-to-fine hierarchical view
+//   eq.12 Ŝv(d) = (Sv(d) − min) / (max − min) per-view min-max normalisation
+//   eq.13 Sfuse = ρ Ŝprimary + (1−ρ) Ŝsecondary
+//   eq.14 C(q) = Dedup(M ∪ Ng(M) ∪ Nh(M))    closure: bridges + neighbours
+//   eq.15 R(q) = Rank_ϕ(Filter(C, ϕ))         deterministic calibration
+
+const EVIDENCE_DEFAULTS = {
+  k: 5,               // paper: Top-5 within 0.65 F1 of Top-10 at half the candidates
+  rho: 0.7,           // primary-view weight
+  gamma: 0.85,        // PPR damping
+  pprIterations: 20,
+  maxSpanLines: 60,
+  maxChars: 6000,     // total text budget of R(q)
+  maxCandidateFiles: 24,
+};
+
+const IDENT = /[A-Za-z_$][\w$]*/g;
+// Verb forms only: "call sites" is a concept, "who calls X" is a usage question.
+const RELATION_WORDS = new Set(["calls", "caller", "callers", "uses", "usages", "used", "using", "imports", "imported", "depends", "references", "referenced", "invokes", "invoked"]);
+const HUB_FRACTION = 0.25;
+const HUB_MIN = 8;
+
+/** Light suffix stripping so "terminated" ⊇ "terminat" matches "terminate"; deterministic, no dictionary. */
+export function stem(token) {
+  if (token.length < 5) return token;
+  return token.replace(/(ations?|ings?|ed|es|e|s|ly|ers?)$/, (m) => (token.length - m.length >= 4 ? "" : m));
+}
+
+function splitIdentifier(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+/** eq.6: query profile with subjects, keywords/stems, answer type, test/doc flags, route. */
+export function profileQuery(query) {
+  const { tokens, wantsTest, wantsType, wantsDoc } = tokenizeQuery(query);
+  const words = query.match(IDENT) || [];
+  // Subjects are identifier-shaped words (camelCase / snake_case): they anchor the graph view.
+  const subjects = words.filter((w) => /[a-z][A-Z]|_/.test(w));
+  const usage = words.some((w) => RELATION_WORDS.has(w.toLowerCase()));
+  const relational = usage || subjects.length > 0;
+  return {
+    subjects: [...new Set(subjects)],
+    keywords: tokens,
+    stems: [...new Set(tokens.map(stem))],
+    answerType: usage ? "usage" : "definition",
+    flags: { wantsTest, wantsType, wantsDoc },
+    route: relational ? "relational" : "local", // eq.7
+  };
+}
+
+// ---- substrate: spans (context units) from the structural surface ----
+
+function spansOf(entry, filePath, maxSpanLines) {
+  const lines = WorkspaceIndex.linesOf(entry);
+  const base = { path: filePath, entry, lower: lines.lower, lines };
+  const declared = WorkspaceIndex.spansOf(entry);
+  if (declared.length === 0) {
+    return [{ ...base, id: filePath + ":1", start: 1, end: Math.min(lines.raw.length, maxSpanLines), name: path.basename(filePath), kind: "file" }];
+  }
+  return declared.map((s, i) => ({ ...base, ...s, id: filePath + ":" + s.start, end: Math.min(s.end, s.start + maxSpanLines - 1), index: i }));
+}
+
+function spanLines(span) {
+  return span.lower.slice(span.start - 1, span.end);
+}
+
+// ---- eq.3 / eq.4: entity–context graph over candidate spans ----
+
+function buildGraph(spans) {
+  const entityNames = new Set(spans.map((s) => s.name).filter((n) => n && n.length > 2));
+  const spanEntities = new Map(); // span.id → Map(entity → w(d,e))
+  const entitySpans = new Map();  // entity → Set(span.id)
+  for (const span of spans) {
+    const counts = new Map();
+    let total = 0;
+    const { idents } = span.lines;
+    for (let li = span.start - 1; li < span.end; li++) {
+      for (const word of idents[li]) {
+        if (!entityNames.has(word)) continue;
+        counts.set(word, (counts.get(word) || 0) + 1);
+        total += 1;
+      }
+    }
+    const weights = new Map();
+    for (const [e, c] of counts) {
+      weights.set(e, c / total); // eq.4
+      if (!entitySpans.has(e)) entitySpans.set(e, new Set());
+      entitySpans.get(e).add(span.id);
+    }
+    spanEntities.set(span.id, weights);
+  }
+  // Entities present in a large share of spans (isString, path, …) carry no query signal; keep them out of propagation.
+  const hubLimit = Math.max(HUB_MIN, Math.floor(spans.length * HUB_FRACTION));
+  const hubs = new Set([...entitySpans].filter(([, ids]) => ids.size > hubLimit).map(([e]) => e));
+  return { entityNames, spanEntities, entitySpans, hubs, byId: new Map(spans.map((s) => [s.id, s])) };
+}
+
+// ---- eq.8 / eq.9: entity activation and one propagation step ----
+
+function lexicalSim(a, b) {
+  const ta = new Set(splitIdentifier(a));
+  const tb = new Set(splitIdentifier(b));
+  if (ta.size === 0 || tb.size === 0) return 0;
+  let inter = 0;
+  for (const t of ta) if (tb.has(t)) inter++;
+  return inter / (ta.size + tb.size - inter);
+}
+
+function activateEntities(profile, graph) {
+  const eta = new Map();
+  const anchors = profile.subjects.length ? profile.subjects : profile.keywords;
+  for (const anchor of anchors) {
+    let best = null;
+    let bestSim = 0;
+    for (const e of graph.entityNames) {
+      const sim = e.toLowerCase() === anchor.toLowerCase() ? 1 : lexicalSim(e, anchor);
+      if (sim > bestSim) {
+        bestSim = sim;
+        best = e;
+      }
+    }
+    if (best && bestSim >= 0.5) eta.set(best, Math.max(eta.get(best) || 0, bestSim)); // eq.8
+  }
+  return eta;
+}
+
+function querySim(profile, lowerLine) {
+  let hits = 0;
+  for (const t of profile.stems) if (lowerLine.includes(t)) hits++;
+  return profile.stems.length ? hits / profile.stems.length : 0;
+}
+
+/** Co-occurring entities on one query-relevant line receive act·sim(q,z)·idf (eq.9, IDF-damped). */
+function activateCooccurring(e, line, weight, spanId, graph, eta1) {
+  for (const [other] of graph.spanEntities.get(spanId)) {
+    if (other === e || graph.hubs.has(other) || !line.includes(other.toLowerCase())) continue;
+    const idf = 1 / Math.log2(1 + graph.entitySpans.get(other).size);
+    eta1.set(other, (eta1.get(other) || 0) + weight * idf);
+  }
+}
+
+function propagateFrom(e, act, graph, profile, eta1) {
+  const eLower = e.toLowerCase();
+  for (const spanId of graph.entitySpans.get(e) || []) {
+    for (const line of spanLines(graph.byId.get(spanId))) {
+      if (!line.includes(eLower)) continue;
+      const sim = querySim(profile, line);
+      if (sim > 0) activateCooccurring(e, line, act * sim, spanId, graph, eta1);
+    }
+  }
+}
+
+function propagate(eta0, spans, graph, profile) {
+  const eta1 = new Map(eta0);
+  for (const [e, act] of eta0) propagateFrom(e, act, graph, profile, eta1);
+  return eta1;
+}
+
+// ---- eq.10: personalized PageRank over spans ----
+
+function resetDistribution(spans, graph, eta, prior) {
+  const n = spans.length;
+  const reset = new Float64Array(n);
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    let r = prior[i];
+    for (const [e, w] of graph.spanEntities.get(spans[i].id)) if (!graph.hubs.has(e)) r += (eta.get(e) || 0) * w;
+    reset[i] = r;
+    sum += r;
+  }
+  if (sum > 0) for (let i = 0; i < n; i++) reset[i] /= sum;
+  return { reset, sum };
+}
+
+/**
+ * Transition structure d → d' = Σ_e w(d,e)·w(d',e) over shared non-hub entities plus 0.5 per in-file
+ * neighbour (Edd). Kept factored through the entity layer so an iteration costs O(nnz), never O(n²).
+ */
+function transitionStructure(spans, graph) {
+  const n = spans.length;
+  const entities = [...graph.entitySpans].filter(([e, ids]) => ids.size >= 2 && !graph.hubs.has(e)).map(([e]) => e);
+  const eIndex = new Map(entities.map((e, i) => [e, i]));
+  const spanTerms = spans.map((s) => {
+    const terms = [];
+    for (const [e, w] of graph.spanEntities.get(s.id)) if (eIndex.has(e)) terms.push([eIndex.get(e), w]);
+    return terms;
+  });
+  const entityMass = new Float64Array(entities.length);
+  for (let i = 0; i < n; i++) for (const [ei, w] of spanTerms[i]) entityMass[ei] += w;
+  const neighbours = spans.map((s, i) => [i - 1, i + 1].filter((j) => j >= 0 && j < n && spans[j].path === s.path));
+  const outWeight = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    let out = 0.5 * neighbours[i].length;
+    for (const [ei, w] of spanTerms[i]) out += w * (entityMass[ei] - w);
+    outWeight[i] = out;
+  }
+  return { spanTerms, entityCount: entities.length, neighbours, outWeight };
+}
+
+function pushStep(pi, next, acc, structure, gamma) {
+  const { spanTerms, neighbours, outWeight } = structure;
+  let dangling = 0;
+  for (let i = 0; i < pi.length; i++) {
+    if (outWeight[i] === 0) {
+      dangling += pi[i];
+      continue;
+    }
+    const flow = (gamma * pi[i]) / outWeight[i];
+    for (const [ei, w] of spanTerms[i]) {
+      acc[ei] += flow * w;
+      next[i] -= flow * w * w; // remove the d → d self term
+    }
+    for (const j of neighbours[i]) next[j] += flow * 0.5;
+  }
+  return dangling;
+}
+
+function pageRank(spans, graph, eta, prior, { gamma, pprIterations }) {
+  const n = spans.length;
+  const { reset, sum } = resetDistribution(spans, graph, eta, prior);
+  if (sum === 0) return reset;
+  const structure = transitionStructure(spans, graph);
+  const acc = new Float64Array(structure.entityCount);
+  let pi = Float64Array.from(reset);
+  for (let iter = 0; iter < pprIterations; iter++) {
+    const next = new Float64Array(n);
+    acc.fill(0);
+    const dangling = pushStep(pi, next, acc, structure, gamma);
+    for (let i = 0; i < n; i++) {
+      for (const [ei, w] of structure.spanTerms[i]) next[i] += acc[ei] * w;
+      next[i] += (1 - gamma) * reset[i] + gamma * dangling * reset[i]; // dangling mass follows the reset
+    }
+    pi = next;
+  }
+  return pi;
+}
+
+// ---- eq.11: hierarchical view (file → span → line) ----
+
+function nameDefinitionScore(span, profile, usage) {
+  if (usage) return 0; // eq.15 Rank_ϕ: a usage question is answered by callers, not the definer
+  const nameTokens = splitIdentifier(span.name || "");
+  let def = 0;
+  for (const t of profile.stems) if (nameTokens.some((n) => n.startsWith(t))) def += 40;
+  return def;
+}
+
+function mentionScore(span, profile, usage, skipDeclaration) {
+  const perHit = usage ? 15 : 5;
+  let mentions = 0;
+  let bestLine = span.start;
+  let bestHits = 0;
+  const lines = spanLines(span);
+  for (let i = skipDeclaration ? 1 : 0; i < lines.length; i++) {
+    let hits = 0;
+    for (const t of profile.stems) if (lines[i].includes(t)) hits++;
+    if (hits > bestHits) {
+      bestHits = hits;
+      bestLine = span.start + i;
+    }
+    mentions += hits * hits * perHit; // several query stems on one line is strong evidence
+  }
+  return { mentions, bestLine };
+}
+
+function hierarchicalScores(spans, fileScores, profile) {
+  const usage = profile.answerType === "usage";
+  return spans.map((span) => {
+    const definesSubject = profile.subjects.includes(span.name);
+    const def = nameDefinitionScore(span, profile, usage);
+    const { mentions, bestLine } = mentionScore(span, profile, usage, usage && definesSubject);
+    span.bestLine = bestLine;
+    span.support = def + mentions; // span-level lexical evidence; file-level bonuses do not count
+    const fileScore = Math.max(0, fileScores.get(span.path) || 0);
+    return fileScore / 2 + def + Math.min(mentions, usage ? 200 : 120) + (span.isExport ? 10 : 0);
+  });
+}
+
+// ---- eq.12 / eq.13 ----
+
+function normalize(scores) {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const s of scores) {
+    if (s < min) min = s;
+    if (s > max) max = s;
+  }
+  if (!(max > min)) return scores.map(() => 1);
+  return scores.map((s) => (s - min) / (max - min));
+}
+
+// ---- candidate files (boundary + topology + entity hits) ----
+
+function candidateFiles(files, profile, index, limit) {
+  const scored = [];
+  for (const f of files) {
+    const s = scorePathTopology(f, profile.keywords, profile.flags);
+    if (s > 0) scored.push({ f, s });
+  }
+  scored.sort((a, b) => b.s - a.s);
+  const chosen = new Set(scored.slice(0, limit).map(({ f }) => f));
+  const anchors = (profile.subjects.length ? profile.subjects : profile.keywords).map((a) => a.toLowerCase()).filter((a) => a.length > 2);
+  const hits = anchors.length ? index.filesContaining(files, anchors, true) : [];
+  for (const f of hits) {
+    if (chosen.size >= limit) break;
+    if (profile.flags.wantsTest || scorePathTopology(f, profile.keywords, profile.flags) > -50) chosen.add(f);
+  }
+  return { files: [...chosen], fileScores: new Map(scored.map(({ f, s }) => [f, s])) };
+}
+
+// ---- eq.14 / eq.15 ----
+
+function bridgesFor(i, spans, graph, fused, definers, chosen) {
+  const byId = graph.byId;
+  const bridges = [];
+  for (const [e, w] of graph.spanEntities.get(spans[i].id)) {
+    const defId = definers.get(e);
+    if (!defId || graph.hubs.has(e) || chosen.has(defId) || defId === spans[i].id || w < 0.15) continue;
+    const definer = byId.get(defId);
+    if (definer.end - definer.start < 2) continue; // one-line helpers add no understanding
+    bridges.push({ id: defId, w: w * fused[definer.index0] });
+  }
+  return bridges.sort((a, b) => b.w - a.w).slice(0, 2);
+}
+
+function closure(main, spans, graph, fused, k) {
+  spans.forEach((s, i) => (s.index0 = i));
+  const chosen = new Map(main.map((i) => [spans[i].id, { i, why: "main" }]));
+  const definers = new Map();
+  for (const s of spans) if (s.name) definers.set(s.name, s.id);
+  const neighboursOf = (i) => [i - 1, i + 1].filter((j) => j >= 0 && j < spans.length && spans[j].path === spans[i].path);
+  for (const i of main) {
+    // Ng: spans that define identifiers this span uses (relational bridges).
+    for (const b of bridgesFor(i, spans, graph, fused, definers, chosen)) chosen.set(b.id, { i: graph.byId.get(b.id).index0, why: "bridge" });
+    // Nh: in-file neighbours that still carry query signal.
+    for (const j of neighboursOf(i)) {
+      if (fused[j] > 0.2 && !chosen.has(spans[j].id)) chosen.set(spans[j].id, { i: j, why: "neighbor" });
+    }
+  }
+  const supports = [...chosen.values()].filter((c) => c.why !== "main").sort((a, b) => fused[b.i] - fused[a.i]).slice(0, k);
+  return [...main.map((i) => ({ i, why: "main" })), ...supports];
+}
+
+function render(spans, picks, fused, opts, root) {
+  const out = [];
+  let budget = opts.maxChars;
+  for (const { i, why } of picks) {
+    const span = spans[i];
+    const lines = span.lines.raw.slice(span.start - 1, span.end);
+    let text = lines.join("\n");
+    if (text.length > budget) text = text.slice(0, Math.max(0, budget - 1)) + "…";
+    budget -= text.length;
+    out.push({
+      path: path.relative(root, span.path) || span.path,
+      lines: [span.start, span.start + lines.length - 1],
+      name: span.name,
+      kind: span.kind,
+      why,
+      text,
+    });
+    if (budget <= 0) break;
+  }
+  return out;
+}
+
+/**
+ * R(q): top-K provenance-bearing source spans for a concept query, selected without any model call.
+ * @returns {{ route: string, spans: Array<{path, lines, name, kind, why, text}> }}
+ */
+export async function selectEvidence({ query, root, searchDir, index, overlayText = () => undefined, options = {} }) {
+  const opts = { ...EVIDENCE_DEFAULTS, ...options };
+  const profile = profileQuery(query);
+  if (profile.keywords.length === 0) throw new Error("evidence requires at least one searchable concept keyword");
+  const files = await index.files(searchDir || root);
+  if (files.length === 0) throw new Error(`no files found to search in ${searchDir || root}`);
+
+  const { files: chosenFiles, fileScores } = candidateFiles(files, profile, index, opts.maxCandidateFiles);
+  const spans = [];
+  for (const f of chosenFiles) {
+    const pending = overlayText(f);
+    const entry = pending === undefined ? index.entry(f) : WorkspaceIndex.fromText(f, pending);
+    if (!entry) continue;
+    spans.push(...spansOf(entry, f, opts.maxSpanLines));
+  }
+  if (spans.length === 0) return { route: profile.route, spans: [] };
+
+  const graph = buildGraph(spans);
+  const hier = hierarchicalScores(spans, fileScores, profile);
+  const hierNorm = normalize(hier);
+  const eta = propagate(activateEntities(profile, graph), spans, graph, profile);
+  const pi = pageRank(spans, graph, eta, hierNorm.map((s) => s * 0.5), opts);
+  const graphNorm = normalize([...pi]);
+
+  const [primary, secondary] = profile.route === "relational" ? [graphNorm, hierNorm] : [hierNorm, graphNorm];
+  const fused = primary.map((p, i) => opts.rho * p + (1 - opts.rho) * secondary[i]); // eq.13
+
+  // eq.15 Filter: boundary/type hard constraints and lexical support; Rank_ϕ: answer-type compatibility.
+  const usage = profile.answerType === "usage";
+  const admissible = spans.map((s, i) => i).filter((i) => {
+    const p = spans[i].path;
+    const isDoc = /\.(md|mdx|rst|txt)$/i.test(p);
+    return spans[i].support > 0 && (profile.flags.wantsTest || !isTestPath(p)) && (profile.flags.wantsDoc || !isDoc);
+  });
+  for (const i of admissible) {
+    if (usage && profile.subjects.includes(spans[i].name)) fused[i] *= 0.5; // a usage question is answered by callers
+  }
+  const ranked = admissible.sort((a, b) => fused[b] - fused[a] || spans[a].path.localeCompare(spans[b].path) || spans[a].start - spans[b].start);
+  const main = ranked.slice(0, opts.k);
+  const picks = closure(main, spans, graph, fused, opts.k);
+  return { route: profile.route, spans: render(spans, picks, fused, opts, root) };
+}

package/fuzzy.js

@@ -0,0 +1,182 @@
+// Typo-resistant fuzzy path matching and frecency, ported from fff (dmtrKovalenko/fff)
+// to plain JS so path search stays in-process: no binary, no spawn.
+//
+// fff pieces reproduced here:
+//   - frizbee-style fuzzy match with max_typos (skipped needle chars), boundary / consecutive /
+//     capitalization bonuses, smart-case (uppercase in query ⇒ case-sensitive)
+//   - filename bonus: exact filename +40% of base, filename match +20%
+//   - frecency boost: base × frecency / 100, AI-mode decay (3-day half-life, 7-day window)
+//     plus modification-recency boosts (30s/5m/15m/1h/4h thresholds)
+//   - git-modified boost: +15% of base
+//   - distance penalty from the current (last touched) file: −1 per directory hop, floor −20
+
+const AI_DECAY = Math.LN2 / 3;            // per day
+const AI_MAX_HISTORY_DAYS = 7;
+const MAX_TIMESTAMPS_PER_FILE = 128;
+const AI_MODIFICATION_THRESHOLDS = [[16, 30], [8, 300], [4, 900], [2, 3600], [1, 14400]]; // [boost, seconds]
+
+export class Frecency {
+  constructor() {
+    this.access = new Map(); // path → number[] (epoch seconds, newest last)
+  }
+
+  record(filePath, at = Date.now() / 1000) {
+    let list = this.access.get(filePath);
+    if (!list) this.access.set(filePath, (list = []));
+    list.push(at);
+    if (list.length > MAX_TIMESTAMPS_PER_FILE) list.splice(0, list.length - MAX_TIMESTAMPS_PER_FILE);
+  }
+
+  /** Σ exp(−λ·age) over accesses in the window, plus a step boost for a recently modified file. */
+  score(filePath, mtimeSec, now = Date.now() / 1000) {
+    let total = 0;
+    const cutoff = now - AI_MAX_HISTORY_DAYS * 86400;
+    for (const t of this.access.get(filePath) || []) {
+      if (t < cutoff) continue;
+      total += Math.exp(-AI_DECAY * ((now - t) / 86400));
+    }
+    if (mtimeSec) {
+      const age = now - mtimeSec;
+      for (const [boost, seconds] of AI_MODIFICATION_THRESHOLDS) {
+        if (age <= seconds) {
+          total += boost;
+          break;
+        }
+      }
+    }
+    return total;
+  }
+}
+
+const SEPARATORS = new Set(["/", "\\", "_", "-", ".", " "]);
+
+function isBoundary(hay, i) {
+  if (i === 0) return true;
+  const prev = hay[i - 1];
+  if (SEPARATORS.has(prev)) return true;
+  const c = hay[i];
+  return c >= "A" && c <= "Z" && !(prev >= "A" && prev <= "Z");
+}
+
+/**
+ * Greedy forward match with backward tightening (fzf v1). Returns null or
+ * { score, start, end }. Score: +16 boundary, +8 consecutive, +4 case match, −1 per gap char.
+ */
+function matchOnce(needle, hay, caseSensitive) {
+  const hayCmp = caseSensitive ? hay : hay.toLowerCase();
+  const nCmp = caseSensitive ? needle : needle.toLowerCase();
+  let hi = 0;
+  let firstAt = -1;
+  for (let ni = 0; ni < nCmp.length; ni++) {
+    hi = hayCmp.indexOf(nCmp[ni], hi);
+    if (hi < 0) return null;
+    if (firstAt < 0) firstAt = hi;
+    hi++;
+  }
+  const end = hi;
+  // Tighten: walk backwards from end to find the latest possible start.
+  let start = end;
+  for (let ni = nCmp.length - 1; ni >= 0; ni--) {
+    start = hayCmp.lastIndexOf(nCmp[ni], start - 1);
+  }
+  return { score: scoreAlignment(needle, nCmp, hay, hayCmp, start), start, end };
+}
+
+/** +16 boundary, +8 consecutive, +4 exact-case, −1 per skipped haystack char. */
+function scoreAlignment(needle, nCmp, hay, hayCmp, start) {
+  let score = 0;
+  let prev = -2;
+  let cursor = start;
+  for (let ni = 0; ni < nCmp.length; ni++) {
+    const at = hayCmp.indexOf(nCmp[ni], cursor);
+    score += isBoundary(hay, at) ? 16 : 0;
+    score += at === prev + 1 ? 8 : 0;
+    score += hay[at] === needle[ni] ? 4 : 0;
+    score -= prev >= 0 ? at - prev - 1 : 0;
+    prev = at;
+    cursor = at + 1;
+  }
+  return score;
+}
+
+/** Best match allowing up to maxTypos skipped needle characters. */
+export function fuzzyMatch(needle, hay, { maxTypos = 0, caseSensitive = false } = {}) {
+  const direct = matchOnce(needle, hay, caseSensitive);
+  if (direct) return { ...direct, typos: 0, exact: hay.toLowerCase() === needle.toLowerCase() };
+  if (maxTypos <= 0 || needle.length < 3) return null;
+  let best = null;
+  for (let i = 0; i < needle.length; i++) {
+    const shorter = needle.slice(0, i) + needle.slice(i + 1);
+    const m = fuzzyMatch(shorter, hay, { maxTypos: maxTypos - 1, caseSensitive });
+    if (!m) continue;
+    const scored = { ...m, score: m.score - 12, typos: m.typos + 1, exact: false };
+    if (!best || scored.score > best.score) best = scored;
+  }
+  return best;
+}
+
+export function smartCase(query) {
+  return /[A-Z]/.test(query);
+}
+
+/** fff distance penalty: directory hops from the current file's directory, floor −20. */
+function distancePenalty(currentDir, candidateDir) {
+  if (!currentDir) return 0;
+  const a = currentDir.split("/").filter(Boolean);
+  const b = candidateDir.split("/").filter(Boolean);
+  let common = 0;
+  while (common < a.length && common < b.length && a[common] === b[common]) common++;
+  const depth = a.length - common;
+  return Math.max(-20, -depth);
+}
+
+/**
+ * Rank file paths for a query the fff way. paths are workspace-relative "/"-joined.
+ * ctx: { frecency: Frecency, mtimeOf: (path) => sec, modified: Set(path), currentFile?: string, maxTypos }
+ */
+export function rankPaths(query, paths, ctx = {}) {
+  const parts = query.trim().split(/\s+/).filter((p) => p.length >= 2);
+  if (parts.length === 0) return [];
+  const caseSensitive = smartCase(query);
+  const maxTypos = ctx.maxTypos ?? (parts[0].length >= 6 ? 2 : parts[0].length >= 4 ? 1 : 0);
+  const currentDir = ctx.currentFile ? ctx.currentFile.slice(0, ctx.currentFile.lastIndexOf("/") + 1) : "";
+  const out = [];
+  for (const rel of paths) {
+    const matched = matchParts(parts, rel, maxTypos, caseSensitive);
+    if (!matched) continue;
+    const { base, first, exact } = matched;
+    const filenameStart = rel.lastIndexOf("/") + 1;
+    const boosts = filenameBonus(base, rel, filenameStart, first, parts[0]) + contextBoost(base, rel, ctx) + distancePenalty(currentDir, rel.slice(0, filenameStart));
+    out.push({ path: rel, score: base + boosts, exact, typos: first.typos });
+  }
+  out.sort((a, b) => b.score - a.score || a.path.length - b.path.length || a.path.localeCompare(b.path));
+  return out;
+}
+
+/** Every query part must match; later parts get at most one typo (fff narrows per part). Score is the average. */
+function matchParts(parts, rel, maxTypos, caseSensitive) {
+  let sum = 0;
+  let first = null;
+  let exact = true;
+  for (let pi = 0; pi < parts.length; pi++) {
+    const m = fuzzyMatch(parts[pi], rel, { maxTypos: pi === 0 ? maxTypos : Math.min(maxTypos, 1), caseSensitive });
+    if (!m) return null;
+    first ??= m;
+    sum += m.score;
+    exact = exact && m.exact;
+  }
+  return { base: Math.max(1, Math.round(sum / parts.length)), first, exact };
+}
+
+/** fff: exact filename +40% of base, any filename match +20%. */
+function filenameBonus(base, rel, filenameStart, first, needle) {
+  if (first.start < filenameStart) return 0;
+  return rel.slice(filenameStart).toLowerCase() === needle.toLowerCase() ? Math.floor((base * 2) / 5) : Math.floor(base / 5);
+}
+
+/** fff: frecency boost base·f/100 and +15% for git-modified files. */
+function contextBoost(base, rel, ctx) {
+  const frecency = ctx.frecency ? ctx.frecency.score(rel, ctx.mtimeOf?.(rel)) : 0;
+  const gitBoost = ctx.modified?.has(rel) ? Math.floor((base * 15) / 100) : 0;
+  return Math.floor((base * frecency) / 100) + gitBoost;
+}

package/guest-worker.js

@@ -10,8 +10,8 @@ const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
 const compiledCache = new Map();
 const COMPILED_CACHE_MAX = 256;
 const PARAMS = [
-  "nova", "tools", "console", "parallel", "pipeline",
-  "read", "write", "edit", "patch", "surface", "snap", "bash", "exec", "speculate",
+  "nova", "console", "parallel", "pipeline",
+  "read", "write", "edit", "patch", "surface", "snap", "evidence", "bash", "exec", "speculate",
 ];
 // V8 and JSC both place the body on the line after the synthesized header.
 const BODY_LINE_OFFSET = 2;
@@ -228,19 +228,22 @@ function buildGuestApi(available) {
         return { ok: false, committed: false, error: err instanceof Error ? err.message : String(err) };
       }
     },
-    surface: async (filePath) => unwrapJsonValue(await rpc("surface", [filePath])),
-    snap: async (query, targetPath) => unwrapJsonValue(await rpc("snap", [query, targetPath])),
+    surface: async (filePath) => unwrapJsonValue(await rpc("call", ["surface", { path: filePath }])),
+    evidence: async (query, opts) => unwrapJsonValue(await rpc("call", ["evidence", { query, ...opts }])),
+    snap: async (query, targetPath) => unwrapJsonValue(await rpc("call", ["snap", { query, path: targetPath }])),
     has: (name) => availableSet.has(name),
   };
 
-  const read = async (p, offset, limit) => {
+  // read(path, offset?, limit?) or read(path, { about, offset, limit, maxChars })
+  const readArgs = (p, a, b) => (isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b });
+  const read = async (p, a, b) => {
     if (Array.isArray(p)) {
-      const res = await nova.call("read", { path: p, offset, limit });
+      const res = await nova.call("read", readArgs(p, a, b));
       if (Array.isArray(res?.items)) return res.items;
       // Captured host executor without batch support: fan out.
-      return Promise.all(p.map((item) => read(item, offset, limit)));
+      return Promise.all(p.map((item) => read(item, a, b)));
     }
-    return unwrapValue(await nova.call("read", { path: p, offset, limit }));
+    return unwrapValue(await nova.call("read", readArgs(p, a, b)));
   };
   const write = async (p, content) => unwrapValue(await nova.call("write", { path: p, content }));
   const edit = async (p, oldText, newText) => unwrapValue(await nova.call("edit", { path: p, oldText, newText }));
@@ -269,7 +272,7 @@ function buildGuestApi(available) {
     return bash([command, ...args].map(quoteShellArg).join(" "), opts);
   };
 
-  return { nova, read, write, edit, patch, surface: nova.surface, snap: nova.snap, bash, exec, speculate: nova.speculate };
+  return { nova, read, write, edit, patch, surface: nova.surface, snap: nova.snap, evidence: nova.evidence, bash, exec, speculate: nova.speculate };
 }
 
 function makeConsole(runId, limits) {
@@ -311,8 +314,8 @@ async function handleRun(msg) {
   const scopedConsole = makeConsole(runId, limits);
   try {
     const value = await compiled(
-      api.nova, api.nova, scopedConsole, runParallel, runPipeline,
-      api.read, api.write, api.edit, api.patch, api.surface, api.snap, api.bash, api.exec, api.speculate,
+      api.nova, scopedConsole, runParallel, runPipeline,
+      api.read, api.write, api.edit, api.patch, api.surface, api.snap, api.evidence, api.bash, api.exec, api.speculate,
     );
     if (runId !== activeRunId) return;
     let plain;