pi-supernova 0.0.11 → 0.1.0

package/check.js

@@ -0,0 +1,166 @@
+// Quick structural check after an edit, not a parser. Catches the edit failures models make
+// most: an unbalanced brace/bracket/paren or an unterminated string, with the line it happened
+// on, so a broken edit is known now instead of after a test run. JSON is checked exactly.
+
+const OPEN = { "{": "}", "[": "]", "(": ")" };
+const CLOSE = new Set(["}", "]", ")"]);
+const REGEX_PRECEDERS = new Set(["(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+", "-", "*", "%", "<", ">", "~", "^", "return", "typeof", "case", "do", "else", "in", "of"]);
+
+function skipString(text, i, quote) {
+  for (let j = i + 1; j < text.length; j++) {
+    if (text[j] === "\\") {
+      j++;
+      continue;
+    }
+    if (text[j] === quote) return j + 1;
+    if (quote !== "`" && text[j] === "\n") return -1;
+  }
+  return -1;
+}
+
+function skipTemplate(text, i, stack) {
+  for (let j = i + 1; j < text.length; j++) {
+    if (text[j] === "\\") {
+      j++;
+      continue;
+    }
+    if (text[j] === "`") return j + 1;
+    if (text[j] === "$" && text[j + 1] === "{") {
+      const end = balancedEnd(text, j + 1, stack);
+      if (end < 0) return -1;
+      j = end - 1; // loop increment lands on the char after "}"
+    }
+  }
+  return -1;
+}
+
+/** Index just past the "}" matching the "{" at i, scanning nested code; −1 when unbalanced. */
+function balancedEnd(text, i, stack) {
+  const depth = stack.length;
+  const r = scan(text, i, stack, depth);
+  return r.error ? -1 : r.end;
+}
+
+function skipComment(text, i) {
+  if (text[i + 1] === "/") {
+    const nl = text.indexOf("\n", i);
+    return nl < 0 ? text.length : nl;
+  }
+  const end = text.indexOf("*/", i + 2);
+  return end < 0 ? text.length : end + 2;
+}
+
+function skipRegex(text, i) {
+  let inClass = false;
+  for (let j = i + 1; j < text.length; j++) {
+    const c = text[j];
+    if (c === "\\") {
+      j++;
+      continue;
+    }
+    if (c === "\n") return -1;
+    if (c === "[") inClass = true;
+    else if (c === "]") inClass = false;
+    else if (c === "/" && !inClass) return j + 1;
+  }
+  return -1;
+}
+
+function lineOf(text, i) {
+  let n = 1;
+  for (let j = 0; j < i && j < text.length; j++) if (text[j] === "\n") n++;
+  return n;
+}
+
+const IDENT_START = /[A-Za-z_$]/;
+const IDENT_PART = /[\w$]/;
+
+function readIdentifier(text, i) {
+  let j = i + 1;
+  while (j < text.length && IDENT_PART.test(text[j])) j++;
+  return j;
+}
+
+function consumeQuoted(text, i, stack) {
+  const c = text[i];
+  if (c === "`") {
+    const end = skipTemplate(text, i, stack);
+    return end < 0 ? { error: "unterminated template literal", at: i } : { end, prev: "value" };
+  }
+  const end = skipString(text, i, c);
+  return end < 0 ? { error: "unterminated string", at: i } : { end, prev: "value" };
+}
+
+/** Try to consume a comment, string, template, or regex at i. Returns { end, prev } | { error, at } | null. */
+function consumeLiteral(text, i, stack, prev) {
+  const c = text[i];
+  if (c === '"' || c === "'" || c === "`") return consumeQuoted(text, i, stack);
+  if (c !== "/") return null;
+  if (text[i + 1] === "/" || text[i + 1] === "*") return { end: skipComment(text, i), prev };
+  if (prev !== "" && !REGEX_PRECEDERS.has(prev)) return null;
+  const end = skipRegex(text, i);
+  return end > 0 ? { end, prev: "value" } : null;
+}
+
+/** Push/pop a bracket; returns an error, a stop, or null to continue. */
+function bracket(c, i, stack, stopDepth) {
+  if (OPEN[c]) {
+    stack.push({ c, at: i });
+    return null;
+  }
+  if (!CLOSE.has(c)) return null;
+  const top = stack.pop();
+  if (!top || OPEN[top.c] !== c) return { error: "unexpected '" + c + "'", at: i };
+  if (stopDepth !== undefined && stack.length <= stopDepth) return { end: i + 1 };
+  return null;
+}
+
+/** Skips comments, strings, templates and regex literals; `prev` is the last code token, which decides regex-vs-division. */
+function scan(text, start, stack, stopDepth) {
+  let i = start;
+  let prev = "";
+  while (i < text.length) {
+    const c = text[i];
+    const literal = consumeLiteral(text, i, stack, prev);
+    if (literal) {
+      if (literal.error) return literal;
+      i = literal.end;
+      prev = literal.prev;
+      continue;
+    }
+    if (IDENT_START.test(c)) {
+      const j = readIdentifier(text, i);
+      prev = text.slice(i, j);
+      i = j;
+      continue;
+    }
+    const outcome = bracket(c, i, stack, stopDepth);
+    if (outcome) return outcome;
+    if (!/\s/.test(c)) prev = c;
+    i++;
+  }
+  return { end: i };
+}
+
+const CODE_EXT = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts", ".java", ".kt", ".c", ".cc", ".cpp", ".h", ".hpp", ".cs", ".go", ".rs", ".swift", ".css", ".scss"]);
+
+/** { ok: true } | { ok: false, message }; message names the problem and line. */
+export function quickCheck(text, ext) {
+  if (ext === ".json") {
+    try {
+      JSON.parse(text);
+      return { ok: true, kind: "json" };
+    } catch (err) {
+      return { ok: false, kind: "json", message: String(err.message).replace(/^JSON\.parse: /, "") };
+    }
+  }
+  if (!CODE_EXT.has(ext)) return null;
+  const stack = [];
+  const r = scan(text, 0, stack);
+  if (r.error) return { ok: false, kind: "balance", message: r.error + " at line " + lineOf(text, r.at) };
+  if (stack.length) {
+    const top = stack[stack.length - 1];
+    return { ok: false, kind: "balance", message: "unclosed '" + top.c + "' opened at line " + lineOf(text, top.at) };
+  }
+  return { ok: true, kind: "balance" };
+}

package/config.default.json

@@ -5,6 +5,7 @@
   "maxCallResultChars": 65536,
   "maxReturnChars": 32000,
   "maxHeapMb": 512,
+  "seenWindow": 40,
   "maxLogLines": 100,
   "maxLogLineChars": 4096,
   "maxSearchResults": 12,

package/config.js

@@ -8,7 +8,7 @@ const require = createRequire(import.meta.url);
 const DEFAULTS = require("./config.default.json");
 
 const KNOWN_KEYS = new Set(Object.keys(DEFAULTS));
-const NONNEGATIVE_INTEGER_KEYS = new Set(["maxLogLines"]);
+const NONNEGATIVE_INTEGER_KEYS = new Set(["maxLogLines", "seenWindow"]);
 const POSITIVE_INTEGER_KEYS = new Set([
   "timeoutMs",
   "maxCodeChars",
@@ -81,4 +81,3 @@ export function loadConfig() {
   return mergeConfig(packageDefaults(), user ?? null);
 }
 
-export { userConfigPath, KNOWN_KEYS };

package/decode.js

@@ -1,16 +1,67 @@
-
 const toStr = Object.prototype.toString;
 
 export const isString = (v) => toStr.call(v) === "[object String]";
 export const isObject = (v) => toStr.call(v) === "[object Object]";
 export const isFunction = (v) => toStr.call(v) === "[object Function]" || v instanceof Function;
 export const isNumber = (v) => toStr.call(v) === "[object Number]" && Number.isFinite(v);
-export const isRecord = (v) => v !== null && isObject(v);
 
-export function parseString(v, fallback = "") {
-  return isString(v) ? v : fallback;
+const MAX_DEPTH = 64;
+const MAX_TYPED_ARRAY = 4096;
+
+function plainFromBinary(value) {
+  const bytes = value.byteLength;
+  if (value instanceof ArrayBuffer) value = new Uint8Array(value);
+  else if (value instanceof DataView) value = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (value.length > MAX_TYPED_ARRAY) return "[" + value.constructor.name + " " + bytes + " bytes]";
+  return value instanceof BigInt64Array || value instanceof BigUint64Array
+    ? Array.from(value, x => x.toString() + "n")
+    : Array.from(value);
+}
+
+function plainFromMap(value, seen, depth) {
+  const allStringKeys = [...value.keys()].every(isString);
+  if (!allStringKeys) return [...value].map(([k, v]) => [toPlain(k, seen, depth + 1), toPlain(v, seen, depth + 1)]);
+  const out = Object.create(null);
+  for (const [k, v] of value) out[k] = toPlain(v, seen, depth + 1);
+  return out;
 }
 
-export function parseNonEmptyString(v) {
-  return isString(v) && v.trim().length > 0 ? v.trim() : null;
+function plainFromCollection(value, seen, depth) {
+  if (Array.isArray(value)) return value.map((x) => toPlain(x, seen, depth + 1));
+  if (value instanceof Set) return [...value].map((x) => toPlain(x, seen, depth + 1));
+  if (value instanceof Map) return plainFromMap(value, seen, depth);
+  const out = Object.create(null);
+  for (const k of Object.keys(value)) out[k] = toPlain(value[k], seen, depth + 1);
+  return out;
 }
+
+/** Convert any guest value to structured-clone-safe, JSON-shaped data. */
+export function toPlain(value, seen = new Set(), depth = 0) {
+  if (value === null || value === undefined) return value;
+  const tag = toStr.call(value);
+  if (tag === "[object String]" || tag === "[object Number]" || tag === "[object Boolean]") return value.valueOf();
+  if (tag === "[object BigInt]") return value.toString() + "n";
+  if (isFunction(value)) return "[Function" + (value.name ? " " + value.name : "") + "]";
+  if (tag === "[object Symbol]") return value.toString();
+  if (depth > MAX_DEPTH) return "[Depth]";
+  if (seen.has(value)) return "[Circular]";
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+  if (value instanceof RegExp) return value.toString();
+  if (value instanceof Error) {
+    const out = { name: value.name, message: value.message };
+    if (value.cause !== undefined) out.cause = toPlain(value.cause, seen, depth + 1);
+    return out;
+  }
+  if (value instanceof Promise) return "[Promise]";
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return plainFromBinary(value);
+  if (isFunction(value.toJSON)) return toPlain(value.toJSON(), seen, depth + 1);
+  seen.add(value);
+  try {
+    return plainFromCollection(value, seen, depth);
+  } finally {
+    seen.delete(value);
+  }
+}
+
+// ---- RPC to the host thread ----
+

package/evidence.js

@@ -1,10 +1,11 @@
 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 —
+// 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
@@ -21,7 +22,7 @@ import { tokenizeQuery, scorePathTopology } from "./snap.js";
 //   eq.14 C(q) = Dedup(M ∪ Ng(M) ∪ Nh(M))    closure: bridges + neighbours
 //   eq.15 R(q) = Rank_ϕ(Filter(C, ϕ))         deterministic calibration
 
-export const EVIDENCE_DEFAULTS = {
+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
@@ -36,12 +37,6 @@ const IDENT = /[A-Za-z_$][\w$]*/g;
 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;
-const TYPE_CUES = [
-  ["test", /\b(test|tests|spec)\b/],
-  ["doc", /\b(doc|docs|readme|documentation)\b/],
-  ["config", /\b(config|configuration|settings|option|options|default|defaults)\b/],
-  ["type", /\b(type|types|interface|schema|struct)\b/],
-];
 
 /** Light suffix stripping so "terminated" ⊇ "terminat" matches "terminate"; deterministic, no dictionary. */
 export function stem(token) {
@@ -53,23 +48,20 @@ 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 from the query text and the call's boundary. */
-export function profileQuery(query, root) {
+/** 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;
-  let answerType = usage ? "usage" : "definition";
-  for (const [type, re] of TYPE_CUES) if (re.test(query.toLowerCase())) answerType = type;
   return {
     subjects: [...new Set(subjects)],
     keywords: tokens,
     stems: [...new Set(tokens.map(stem))],
-    answerType,
+    answerType: usage ? "usage" : "definition",
     flags: { wantsTest, wantsType, wantsDoc },
-    boundary: root,
     route: relational ? "relational" : "local", // eq.7
   };
 }
@@ -77,21 +69,13 @@ export function profileQuery(query, root) {
 // ---- substrate: spans (context units) from the structural surface ----
 
 function spansOf(entry, filePath, maxSpanLines) {
-  const { items, lineCount } = WorkspaceIndex.surfaceOf(entry);
   const lines = WorkspaceIndex.linesOf(entry);
-  const lower = lines.lower;
-  if (items.length === 0) {
-    return [{ id: filePath + ":1", path: filePath, start: 1, end: Math.min(lineCount, maxSpanLines), name: path.basename(filePath), kind: "file", entry, lower, lines }];
+  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" }];
   }
-  const spans = [];
-  for (let i = 0; i < items.length; i++) {
-    const start = items[i].line;
-    const nextStart = i + 1 < items.length ? items[i + 1].line : lineCount + 1;
-    let end = Math.min(nextStart - 1, start + maxSpanLines - 1, lineCount);
-    while (end > start && lower[end - 1] === "") end--;
-    spans.push({ id: filePath + ":" + start, path: filePath, start, end, name: items[i].name, kind: items[i].kind, isExport: items[i].isExport === true, entry, lower, lines, index: i });
-  }
-  return spans;
+  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) {
@@ -325,7 +309,7 @@ function normalize(scores) {
 
 // ---- candidate files (boundary + topology + entity hits) ----
 
-function candidateFiles(files, profile, index, limit) {
+function candidateFiles(files, profile, index, limit, overlayText) {
   const scored = [];
   for (const f of files) {
     const s = scorePathTopology(f, profile.keywords, profile.flags);
@@ -334,7 +318,11 @@ function candidateFiles(files, profile, index, limit) {
   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) : [];
+  const pendingHits = files.filter(file => {
+    const pending = overlayText(file);
+    return pending !== undefined && anchors.some(anchor => pending.toLowerCase().includes(anchor));
+  });
+  const hits = anchors.length ? [...new Set([...pendingHits, ...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);
@@ -401,14 +389,19 @@ function render(spans, picks, fused, opts, root) {
  * 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 = {} }) {
+export async function selectEvidence({ query, root, searchDir, index, overlayText = () => undefined, pendingPaths = [], options = {} }) {
   const opts = { ...EVIDENCE_DEFAULTS, ...options };
-  const profile = profileQuery(query, root);
+  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);
+  const searchRoot = path.resolve(searchDir || root);
+  const staged = pendingPaths.filter(file => {
+    const relative = path.relative(searchRoot, file);
+    return relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+  });
+  const files = [...new Set([...await index.files(searchRoot), ...staged])];
   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 { files: chosenFiles, fileScores } = candidateFiles(files, profile, index, opts.maxCandidateFiles, overlayText);
   const spans = [];
   for (const f of chosenFiles) {
     const pending = overlayText(f);
@@ -432,9 +425,8 @@ export async function selectEvidence({ query, root, searchDir, index, overlayTex
   const usage = profile.answerType === "usage";
   const admissible = spans.map((s, i) => i).filter((i) => {
     const p = spans[i].path;
-    const isTestSpan = /(^|[\\/])(test|tests)[\\/]|\.(test|spec)\./.test(p);
     const isDoc = /\.(md|mdx|rst|txt)$/i.test(p);
-    return spans[i].support > 0 && (profile.flags.wantsTest || !isTestSpan) && (profile.flags.wantsDoc || !isDoc);
+    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

package/format.js

@@ -1,4 +1,4 @@
-import { isString } from "./decode.js";
+import { isString, isObject } from "./decode.js";
 
 export function truncateChars(text, maxChars, label = "value") {
   const normalized = isString(text) ? text : String(text ?? "");
@@ -12,22 +12,21 @@ export function truncateChars(text, maxChars, label = "value") {
       originalChars: normalized.length,
     };
   }
-  const head = headEnd(normalized, Math.floor(limit * 0.7));
-  let tail = Math.max(0, limit - head);
+  let head = headEnd(normalized, Math.floor(limit * 0.7));
+  let tail = 0;
   let marker = "";
-  let previousTail = -1;
-  while (tail !== previousTail) {
-    previousTail = tail;
+  for (;;) {
     const omitted = normalized.length - head - tail;
-    marker = `\n…[${label} truncated ${omitted} chars]…\n`;
-    tail = Math.max(0, limit - head - marker.length);
+    marker = "\n…[" + label + " truncated " + omitted + " chars]…\n";
+    if (marker.length > limit) return { text: normalized.slice(0, headEnd(normalized, limit)), truncated: true, originalChars: normalized.length };
+    const budget = limit - marker.length;
+    const nextHead = headEnd(normalized, Math.min(head, budget));
+    const nextTail = normalized.length - tailStartIndex(normalized, Math.max(0, budget - nextHead));
+    if (nextHead === head && nextTail === tail) break;
+    head = nextHead;
+    tail = nextTail;
   }
-  const tailStart = tailStartIndex(normalized, tail);
-  return {
-    text: normalized.slice(0, head) + marker + normalized.slice(tailStart),
-    truncated: true,
-    originalChars: normalized.length,
-  };
+  return { text: normalized.slice(0, head) + marker + normalized.slice(normalized.length - tail), truncated: true, originalChars: normalized.length };
 }
 
 // Lone surrogates in a tool result make the message invalid UTF-8 at the API
@@ -53,7 +52,7 @@ function formatKey(key) {
 
 function formatPrimitive(value) {
   if (value === undefined) return "undefined";
-  if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+  if (Number.isNaN(value) || value === Infinity || value === -Infinity) return String(value);
   return JSON.stringify(value) ?? String(value);
 }
 
@@ -65,7 +64,7 @@ function formatFlatList(value) {
 }
 
 function formatFlat(value) {
-  if (value === null || typeof value !== "object") return formatPrimitive(value);
+  if ((!isObject(value) && !Array.isArray(value))) return formatPrimitive(value);
   if (Array.isArray(value)) return formatFlatList(value);
   let out = "";
   for (const key of Object.keys(value)) {
@@ -83,7 +82,7 @@ function formatFlat(value) {
  */
 export function formatValue(value, indent = "", width = FORMAT_WIDTH) {
   const flat = formatFlat(value);
-  if (value === null || typeof value !== "object" || flat.length + indent.length <= width) return flat;
+  if ((!isObject(value) && !Array.isArray(value)) || flat.length + indent.length <= width) return flat;
   const pad = indent + " ";
   if (Array.isArray(value)) {
     if (value.length === 0) return "[]";

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;
+}