pi-supernova 0.0.11 → 0.1.0

package/index.js

@@ -1,19 +1,14 @@
 import { createRequire } from "node:module";
-import { isString, isFunction, isObject } from "./decode.js";
+import { isString, isFunction } from "./decode.js";
 import { buildCatalog, searchCatalog, describeTool, mergeNativeToolDefinitions } from "./catalog.js";
 import { loadConfig } from "./config.js";
 import { createHostBridge } from "./host-bridge.js";
 import { runGuestProgram, warmGuestWorker } from "./runtime.js";
-import {
-  extractOperationsFromCode,
-  renderSupernovaCall,
-  renderSupernovaResult,
-  SafeText,
-} from "./render.js";
+import { renderSupernovaCall, renderSupernovaResult } from "./render.js";
 
-export { extractOperationsFromCode, renderSupernovaCall, renderSupernovaResult, SafeText };
+export { renderSupernovaCall, renderSupernovaResult };
 
-// Sync only — never top-level await. Dynamic import of host/deps hung OMP plugin load.
+// Sync only, never top-level await. Dynamic import of host/deps hung OMP plugin load.
 const require = createRequire(import.meta.url);
 let Type;
 try {
@@ -71,48 +66,44 @@ function progressEmitter(onUpdate) {
   return emit;
 }
 
+function sessionStats({ programs, returnedChars, collapsedChars, collapsedRuns }) {
+  const total = returnedChars + collapsedChars;
+  const pct = total ? Math.round((collapsedChars / total) * 100) : 0;
+  return `this session: ${programs} programs · ~${Math.round(returnedChars / 4)} tokens returned · ~${Math.round(collapsedChars / 4)} already-seen tokens not re-sent (${pct}%, ${collapsedRuns} runs)`;
+}
+
 function logsBlock(outcome, tail = "") {
   return outcome.logs?.length ? `\n--- logs\n${outcome.logs.join("\n")}${tail}` : "";
 }
 
-function errorText(outcome) {
-  return `error ${outcome.wallMs}ms: ${outcome.error}${logsBlock(outcome)}`;
+function errorText(outcome, call) {
+  return `error #${call} ${outcome.wallMs}ms: ${outcome.error}${logsBlock(outcome)}`;
 }
 
-function successText(outcome) {
+function successText(outcome, call) {
   const truncated = outcome.returnTruncated ? " [return truncated]" : "";
-  const hint = outcome.undefinedReturn ? " (no return statement — add \`return\` to get a value)" : "";
-  return `ok ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
-}
-function unwrapStructuredResult(response, operation) {
-  if (response?.ok === false) {
-    throw new Error(response.value || response.error || `${operation} failed`);
-  }
-  const value = isObject(response) && "value" in response ? response.value : response;
-  if (!isString(value)) return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
+  const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
+  return `ok #${call} ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
-
 const TOOL_DESCRIPTION = `Run one JavaScript program that composes host tools. Async body or arrow; \`return\` a small shaped value (compact literal, capped; strings raw; console.log is captured).
 
 Globals (async):
-read(path|paths, offset?, limit?) → text | text[]
-write(path, text) · edit(path, oldText, newText) · patch(path, unifiedDiff)
+read(path|paths, offset?, limit?) → text | text[] · read(path, {about}) → whole-file outline, only relevant bodies expanded
+write(path, text) · edit(path, oldText, newText) → post-edit lines (no re-read needed) · patch(path, unifiedDiff)
 bash(cmd, {cwd?, timeoutMs?}) → output, throws on non-zero exit · exec(cmd, argv?) quotes argv
-evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question — use before read
+evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question; use before read
 snap(query, root?) → {path, line, signature, context} · surface(path) → {items: [{name, kind, line}]}
 nova.call(name, args) → {ok, value} for any host tool · nova.callMany([{name, args}]) parallel when read-only
 nova.search(query) → [{name, description}] · nova.describe(name) → parameters · nova.has(name) sync
-parallel(thunks) · pipeline(items, ...stages)`;
+parallel(thunks) · pipeline(items, ...stages)
+
+Already-seen lines collapse to "⋯ N lines same as #12 · path:a–b ⋯"; read(path, a, n) re-shows them.`;
 
 export default function piSupernova(pi) {
   const config = loadConfig();
   let cwd = process.cwd();
   let catalog = [];
+  let programSeq = 0;
 
   const bridge = createHostBridge({
     pi,
@@ -120,56 +111,38 @@ export default function piSupernova(pi) {
     getCwd: () => cwd,
   });
 
-  function refreshCatalog() {
-    let tools = [];
-    try {
-      if (isFunction(pi.getAllTools)) {
-        tools = pi.getAllTools() || [];
-      }
-    } catch {
-      tools = [];
-    }
-    const discoverable = mergeNativeToolDefinitions(tools, bridge.executors.keys());
+  function refreshCatalog(target = bridge) {
+    const tools = target.refreshTools();
+    const discoverable = mergeNativeToolDefinitions(tools, target.externalNames())
+      .filter(tool => target.isCallable(tool.name))
+      .map(tool => {
+        const schema = tool.parameters;
+        try {
+          if (isFunction(schema?.toJsonSchema)) return { ...tool, parameters: schema.toJsonSchema() };
+          if (schema && !schema.type && pi.zod?.toJSONSchema && (schema._zod || schema._def)) {
+            return { ...tool, parameters: pi.zod.toJSONSchema(schema, { io: "input" }) };
+          }
+          return tool;
+        } catch (error) {
+          return { ...tool, parameters: undefined, schemaError: error.message };
+        }
+      });
     catalog = buildCatalog(discoverable, config.excludeTools || []);
     return catalog;
   }
 
-  function makeNovaApi() {
+  function makeNovaApi(runBridge, runCatalog, cancel) {
     return {
-      async search(query, limit) {
-        const cat = catalog.length ? catalog : refreshCatalog();
-        const lim = Number.isInteger(limit) ? limit : config.maxSearchResults;
-        return searchCatalog(cat, query, lim);
-      },
-      async describe(name) {
-        const cat = catalog.length ? catalog : refreshCatalog();
-        return describeTool(cat, name);
-      },
-      async call(name, args) {
-        return bridge.call(name, args);
-      },
-      async callMany(calls) {
-        return bridge.callMany(calls);
-      },
-      speculateBegin() {
-        bridge.beginSpeculation();
-      },
-      async speculateCommit() {
-        await bridge.commitSpeculation();
-      },
-      speculateRollback() {
-        bridge.rollbackSpeculation();
-      },
-      names() {
-        const cat = catalog.length ? catalog : refreshCatalog();
-        return [...new Set([...cat.map((t) => t.name), ...bridge.executors.keys(), ...Object.keys(bridge.natives)])];
-      },
-      async surface(filePath) {
-        return unwrapStructuredResult(await bridge.call("surface", { path: filePath }), "surface");
-      },
-      async snap(query, targetPath) {
-        return unwrapStructuredResult(await bridge.call("snap", { query, path: targetPath }), "snap");
-      },
+      search: async (query, limit) => searchCatalog(runCatalog, query, Number.isInteger(limit) ? limit : config.maxSearchResults),
+      describe: async (name) => describeTool(runCatalog, name),
+      call: (name, args) => runBridge.call(name, args),
+      callMany: (calls) => runBridge.callMany(calls),
+      speculateBegin: () => runBridge.beginSpeculation(),
+      speculateCommit: () => runBridge.commitSpeculation(),
+      speculateRollback: () => runBridge.rollbackSpeculation(),
+      names: () => runCatalog.map(tool => tool.name),
+      batchRead: runBridge.supportsBatchRead(),
+      cancel,
     };
   }
 
@@ -179,7 +152,7 @@ export default function piSupernova(pi) {
     description: TOOL_DESCRIPTION,
     promptSnippet: "Compose host tools in one JavaScript program",
     promptGuidelines: [
-      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code, call evidence(question) and read only the returned spans; read whole files only to edit them. Return a compact shaped value; keep raw tool output inside the program.",
+      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code: evidence(question) across the repo, or read(path, {about: question}) for one file: full structure, only relevant bodies expanded. Plain read(path) only for lines you will edit. Return a compact shaped value; keep raw tool output inside the program.",
     ],
     parameters: Type.Object({
       code: Type.String({ description: "JavaScript program: async body or arrow function." }),
@@ -192,82 +165,81 @@ export default function piSupernova(pi) {
     renderCall: renderSupernovaCall,
     renderResult: renderSupernovaResult,
     async execute(_id, params, signal, onUpdate, ctx) {
-      if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
+      const runCwd = ctx?.cwd || cwd;
       const runController = new AbortController();
       const abortRun = () => runController.abort(signal?.reason);
       if (signal?.aborted) abortRun();
       else signal?.addEventListener("abort", abortRun, { once: true });
+      const runBridge = bridge.fork({ getCwd: () => runCwd });
+      runBridge.bindCallContext(ctx, runController.signal);
+      runBridge.resetCallBudget();
 
-      bridge.bindCallContext(ctx, runController.signal);
-      bridge.resetCallBudget();
-      refreshCatalog();
-      bridge.beginSpeculation();
+      const call = ++programSeq;
+      runBridge.ledger.beginProgram(call);
       const emitProgress = progressEmitter(onUpdate);
-      bridge.setCallListener((_record, allTrace) => emitProgress(allTrace));
+      runBridge.setCallListener((_record, trace) => emitProgress(trace));
       emitProgress([]);
-
+      const started = performance.now();
       let outcome;
       try {
-        outcome = await runProgram(params, runController.signal, abortRun);
+        const runCatalog = refreshCatalog(runBridge);
+        runBridge.beginSpeculation();
+        outcome = await runGuestProgram({
+          code: params?.code,
+          nova: makeNovaApi(runBridge, runCatalog, abortRun),
+          config: { ...config, timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs },
+          signal: runController.signal,
+          onTimeout: abortRun,
+        });
+        runBridge.close();
+        if (outcome.ok) {
+          if (runBridge.getOverlayDepth() !== 1) throw new Error("program ended with an unfinished nova.speculate branch; await it before returning");
+          await runBridge.commitSpeculation();
+        }
+        else runBridge.rollbackSpeculation();
+      } catch (error) {
+        abortRun();
+        runBridge.close();
+        runBridge.rollbackSpeculation();
+        outcome = { ok: false, error: error instanceof Error ? error.message : String(error), logs: outcome?.logs ?? [], wallMs: Math.round(performance.now() - started) };
       } finally {
-        bridge.setCallListener(null);
+        runBridge.setCallListener(null);
         emitProgress.flush();
         signal?.removeEventListener("abort", abortRun);
       }
-
-      const trace = bridge.getTrace();
-      if (!outcome.ok) {
-        bridge.rollbackSpeculation();
-        return result(errorText(outcome), { ok: false, error: outcome.error, wallMs: outcome.wallMs, logs: outcome.logs, trace });
-      }
-      await bridge.commitSpeculation();
-      return result(successText(outcome), {
-        ok: true,
-        wallMs: outcome.wallMs,
-        returnTruncated: outcome.returnTruncated,
-        logTruncated: outcome.logTruncated,
-        logs: outcome.logs,
-        result: outcome.result,
-        trace,
+      const trace = runBridge.getTrace();
+      const text = outcome.ok ? successText(outcome, call) : errorText(outcome, call);
+      return result(runBridge.ledger.dedupe(text, call), {
+        ok: outcome.ok, error: outcome.error, wallMs: outcome.wallMs,
+        returnTruncated: outcome.returnTruncated, logTruncated: outcome.logTruncated,
+        logs: outcome.logs, result: outcome.result, trace,
       });
     },
   });
 
-  async function runProgram(params, signal, onTimeout) {
-    const runStartedAt = performance.now();
-    const runConfig = {
-      ...config,
-      timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs,
-    };
-    try {
-      return await runGuestProgram({ code: String(params?.code || ""), nova: makeNovaApi(), config: runConfig, signal, onTimeout });
-    } catch (error) {
-      return {
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-        logs: [],
-        wallMs: Math.round(performance.now() - runStartedAt),
-      };
-    }
-  }
-
   pi.on("session_start", (_event, ctx) => {
     if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
+    // A new session is a new model context: nothing has been seen yet.
+    bridge.bindCallContext(ctx);
+    bridge.ledger.reset();
+    programSeq = 0;
     refreshCatalog();
     warmGuestWorker(config).catch(() => {});
   });
 
   pi.registerCommand("supernova", {
-    description: "Show pi-supernova status (catalog size, captured executors)",
+    description: "Show pi-supernova status (callable tools and session statistics)",
     handler: async (_args, ctx) => {
+      bridge.bindCallContext(ctx);
       refreshCatalog();
-      const captured = [...bridge.executors.keys()].sort();
-      const natives = Object.keys(bridge.natives).sort();
+      const external = bridge.externalNames().filter(bridge.isCallable).sort();
+      const natives = Object.keys(bridge.natives).filter(name => bridge.isCallable(name) && !external.includes(name)).sort();
       const lines = [
         `pi-supernova catalog: ${catalog.length} tools`,
-        `captured executors: ${captured.length ? captured.join(", ") : "(none yet — load this package early)"}`,
+        `external tools: ${external.length ? external.join(", ") : "(none)"}`,
         `native adapters: ${natives.join(", ")}`,
         `timeoutMs=${config.timeoutMs} maxCallResultChars=${config.maxCallResultChars} maxReturnChars=${config.maxReturnChars} maxBridgeCalls=${config.maxBridgeCalls} maxHeapMb=${config.maxHeapMb}`,
+        sessionStats(bridge.ledger.stats),
       ];
       ctx.ui.notify(lines.join("\n"), "info");
     },

package/ledger.js

@@ -0,0 +1,150 @@
+const MIN_RUN = 6;
+const MIN_SUBSTANTIVE = 4;
+const MAX_CANDIDATES = 8;
+const DEFAULT_WINDOW = 40;
+const MAX_STORED_LINES = 200_000;
+
+function hashLine(line) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < line.length; i++) hash = Math.imul(hash ^ line.charCodeAt(i), 0x01000193);
+  return hash >>> 0;
+}
+function substantive(line) { return line.trim().length >= 8; }
+function newHistory() {
+  return { results: new Map(), occurrences: new Map(), storedLines: 0, latestCall: 0,
+    stats: { programs: 0, returnedChars: 0, collapsedChars: 0, collapsedRuns: 0 } };
+}
+
+export class SeenLedger {
+  constructor({ window = DEFAULT_WINDOW, history } = {}) {
+    this.window = window;
+    this.history = history ?? newHistory();
+    this.origins = new Map();
+    this.pinned = new Set();
+  }
+  get results() { return this.history.results; }
+  get occurrences() { return this.history.occurrences; }
+  get storedLines() { return this.history.storedLines; }
+  get stats() { return this.history.stats; }
+  fork() { return new SeenLedger({ window: this.window, history: this.history }); }
+
+  reset() {
+    Object.assign(this.history, newHistory());
+    this.origins.clear();
+    this.pinned.clear();
+  }
+
+  beginProgram(call) {
+    this.origins.clear();
+    this.pinned.clear();
+    this.stats.programs++;
+    this.history.latestCall = Math.max(this.history.latestCall, call);
+    for (const old of this.results.keys()) if (old <= this.history.latestCall - this.window) this.forget(old);
+  }
+
+  forget(call) {
+    const entry = this.results.get(call);
+    if (!entry) return;
+    for (const hash of new Set(entry.hashes)) {
+      const kept = (this.occurrences.get(hash) ?? []).filter(item => item.call !== call);
+      if (kept.length) this.occurrences.set(hash, kept);
+      else this.occurrences.delete(hash);
+    }
+    this.history.storedLines -= entry.lines.length;
+    this.results.delete(call);
+  }
+
+  recordOrigin(path, firstLine, lines, pin = false) {
+    if (this.window === 0) return;
+    for (let i = 0; i < lines.length; i++) {
+      const text = lines[i];
+      if (!substantive(text)) continue;
+      if (this.origins.size >= MAX_STORED_LINES && !this.origins.has(text)) this.origins.delete(this.origins.keys().next().value);
+      this.origins.set(text, { path, line: firstLine + i });
+      if (pin) this.pinned.add(text);
+    }
+  }
+
+  runLength(lines, hashes, candidate, index) {
+    const earlier = this.results.get(candidate.call);
+    if (!earlier) return 0;
+    let count = 0;
+    while (index + count < lines.length && candidate.index + count < earlier.lines.length
+      && hashes[index + count] === earlier.hashes[candidate.index + count]
+      && lines[index + count] === earlier.lines[candidate.index + count]
+      && !this.pinned.has(lines[index + count])) count++;
+    return count;
+  }
+
+  longestRun(lines, hashes, index, call) {
+    const candidates = this.occurrences.get(hashes[index]);
+    if (!candidates) return null;
+    let best = null;
+    for (const candidate of candidates.filter(item => item.call < call).slice(-MAX_CANDIDATES)) {
+      const length = this.runLength(lines, hashes, candidate, index);
+      if (length >= MIN_RUN && (!best || length > best.length)) best = { ...candidate, length };
+    }
+    if (!best) return null;
+    let count = 0;
+    for (let i = index; i < index + best.length; i++) if (substantive(lines[i])) count++;
+    return count >= MIN_SUBSTANTIVE ? best : null;
+  }
+
+  citation(lines, index, run) {
+    const earlier = this.results.get(run.call);
+    const origin = offset => this.origins.get(lines[index + offset]) ?? earlier?.origins[run.index + offset];
+    const first = origin(0);
+    if (!first) return "";
+    let expected = first.line;
+    for (let i = 0; i < run.length; i++) {
+      const item = origin(i);
+      if (item && (item.path !== first.path || item.line !== expected)) return "";
+      expected++;
+    }
+    return first.path + ":" + first.line + "–" + (expected - 1);
+  }
+
+  dedupe(text, call) {
+    if (this.window === 0) {
+      this.stats.returnedChars += text.length;
+      return text;
+    }
+    const lines = text.split("\n");
+    const hashes = Uint32Array.from(lines, hashLine);
+    const out = [];
+    let collapsedChars = 0;
+    for (let i = 0; i < lines.length;) {
+      const run = substantive(lines[i]) ? this.longestRun(lines, hashes, i, call) : null;
+      if (!run) { out.push(lines[i++]); continue; }
+      const cite = this.citation(lines, i, run);
+      out.push("⋯ " + run.length + " lines same as #" + run.call + (cite ? " · " + cite : "") + " ⋯");
+      for (let k = 0; k < run.length; k++) collapsedChars += lines[i + k].length + 1;
+      this.stats.collapsedRuns++;
+      i += run.length;
+    }
+    const sent = out.join("\n");
+    this.stats.returnedChars += sent.length;
+    this.stats.collapsedChars += collapsedChars;
+    this.remember(call, out);
+    return sent;
+  }
+
+  remember(call, lines) {
+    if (this.window === 0 || call <= this.history.latestCall - this.window || lines.length > MAX_STORED_LINES) return;
+    if (this.results.has(call)) this.forget(call);
+    for (const old of [...this.results.keys()].sort((a, b) => a - b)) {
+      if (this.storedLines + lines.length <= MAX_STORED_LINES) break;
+      this.forget(old);
+    }
+    const hashes = Uint32Array.from(lines, hashLine);
+    const origins = lines.map(line => this.origins.get(line));
+    for (let i = 0; i < lines.length; i++) {
+      if (!substantive(lines[i])) continue;
+      let list = this.occurrences.get(hashes[i]);
+      if (!list) this.occurrences.set(hashes[i], (list = []));
+      list.push({ call, index: i });
+    }
+    this.results.set(call, { hashes, lines, origins });
+    this.history.storedLines += lines.length;
+  }
+}

package/omp-frame.js

@@ -1,7 +1,7 @@
 /**
  * Shared Pi/OMP rounded tool chrome for supernova.
  *
- * Intentionally self-contained — never dynamic-imports `@oh-my-pi/pi-coding-agent`
+ * Intentionally self-contained: never dynamic-imports `@oh-my-pi/pi-coding-agent`
  * (that hung OMP plugin load). Portable geometry matches native edit/write cards.
  */
 
@@ -43,30 +43,15 @@ function borderPaint(theme, state, borderColor) {
 	return (text) => text;
 }
 
-function resolveStatusIcon({ icon, iconOverride, state }) {
-	if (iconOverride !== undefined) return undefined;
-	if (icon !== undefined) return icon;
-	return state === "error" ? "error" : undefined;
-}
-
-const STATUS_GLYPH = { error: "✗ ", running: "… " };
-const STATUS_COLOR = { error: "error", running: "dim" };
+const STATUS_PREFIX = { error: ["error", "✗ "], running: ["dim", "… "] };
 
-function statusPrefix(theme, resolvedIcon, iconOverride, spinnerFrame) {
-	if (iconOverride) return `${iconOverride} `;
-	const key = resolvedIcon === "error" ? "error" : resolvedIcon === "running" || spinnerFrame ? "running" : undefined;
-	const glyph = STATUS_GLYPH[key];
-	if (!glyph) return "";
-	return theme?.fg ? theme.fg(STATUS_COLOR[key], glyph) : glyph;
-}
-
-function statusHeader(theme, { title, description, state, spinnerFrame, icon, iconOverride }) {
-	const resolvedIcon = resolveStatusIcon({ icon, iconOverride, state });
+function statusHeader(theme, { title, description, state, icon }) {
+	const resolved = icon ?? (state === "error" ? "error" : undefined);
+	const prefixSpec = STATUS_PREFIX[resolved];
+	const prefix = prefixSpec ? (theme?.fg ? theme.fg(prefixSpec[0], prefixSpec[1]) : prefixSpec[1]) : "";
 	const titleText = theme?.fg ? theme.fg("accent", title) : title;
 	const descText = description ? (theme?.fg ? theme.fg("muted", description) : description) : "";
-	const prefix = statusPrefix(theme, resolvedIcon, iconOverride, spinnerFrame);
-	if (!descText) return `${prefix}${titleText}`;
-	return `${prefix}${titleText}: ${descText}`;
+	return descText ? `${prefix}${titleText}: ${descText}` : `${prefix}${titleText}`;
 }
 
 function padLine(line, width, bgFn) {
@@ -142,7 +127,6 @@ function renderPortableFrame(theme, { header, sections = [], state = "pending",
 	const border = borderPaint(theme, state, borderColor);
 	const bgFn = bgFnForState(theme, state);
 	const h = box.horizontal;
-	const v = box.vertical;
 	const cap = h.repeat(3);
 
 	const paintBar = (leftChar, rightChar, label) => {

package/outline.js

@@ -0,0 +1,80 @@
+import { WorkspaceIndex } from "./repo-index.js";
+import { tokenizeQuery } from "./snap.js";
+import { stem } from "./evidence.js";
+
+// read(path, { about }): one call, whole-file structure, only the relevant bodies expanded.
+// L0 (names) and L1 (signatures + line ranges) for every declaration; L2 (full text) for the
+// spans that match the question, within a character budget. The model reads a 600-line file
+// in ~15% of its tokens and knows the exact read(path, offset, limit) to issue for anything folded.
+
+const OUTLINE_DEFAULTS = { maxChars: 8000, maxExpanded: 6, headerLines: 30, maxRefs: 5, references: null };
+
+
+function relevance(span, lower, stems) {
+  if (stems.length === 0) return 0;
+  const nameLower = span.name.toLowerCase();
+  let score = 0;
+  for (const s of stems) if (nameLower.includes(s)) score += 40;
+  for (let i = span.start - 1; i < span.end; i++) {
+    let hits = 0;
+    for (const s of stems) if (lower[i].includes(s)) hits++;
+    score += hits * hits * 5;
+  }
+  return score;
+}
+
+function chooseExpanded(spans, lower, stems, raw, opts) {
+  const scored = spans.map((s, i) => ({ i, r: relevance(s, lower, stems), chars: raw.slice(s.start - 1, s.end).join("\n").length }));
+  scored.sort((a, b) => b.r - a.r || a.i - b.i);
+  const expanded = new Set();
+  let budget = opts.maxChars;
+  // Weak-match cutoff (as fff's weak-match detector): stop once relevance falls below 40% of the best span.
+  const floor = stems.length > 0 ? Math.max(1, scored[0].r * 0.4) : 0;
+  for (const { i, r, chars } of scored) {
+    if (expanded.size >= opts.maxExpanded || r < floor) break;
+    if (chars > budget) continue;
+    expanded.add(i);
+    budget -= chars;
+  }
+  return expanded;
+}
+
+function foldedLine(span) {
+  const body = span.end - span.start;
+  const sig = span.signature.replace(/\s*\{\s*$/, "");
+  return String(span.start).padStart(5) + " " + sig + (body > 0 ? " … " + body + " lines" : "");
+}
+
+function expandedBlock(span, raw, opts) {
+  const out = [];
+  for (let l = span.start; l <= span.end; l++) out.push(String(l).padStart(5) + " " + raw[l - 1]);
+  const refs = opts.references ? opts.references(span.name, span.start) : [];
+  // Who uses this declaration: the relation a reader would otherwise grep for next.
+  if (refs.length) out.push("      // used by: " + refs.slice(0, opts.maxRefs).join(", ") + (refs.length > opts.maxRefs ? " (+" + (refs.length - opts.maxRefs) + ")" : ""));
+  return out.join("\n");
+}
+
+/**
+ * @param entry index entry (text + cached lines/surface)
+ * @param about question or symbol; empty ⇒ pure skeleton (every body folded)
+ */
+export function outlineFile(entry, relPath, about, options = {}) {
+  const opts = { ...OUTLINE_DEFAULTS, ...options };
+  const { raw, lower } = WorkspaceIndex.linesOf(entry);
+  const lineCount = raw.length;
+  const spans = WorkspaceIndex.spansOf(entry).map((s) => ({ ...s, signature: raw[s.start - 1].trim() }));
+  if (spans.length === 0) return null; // no structure: caller falls back to plain text
+  const stems = [...new Set(tokenizeQuery(about || "").tokens.map(stem))];
+  const expanded = chooseExpanded(spans, lower, stems, raw, opts);
+
+  const parts = [];
+  const headerEnd = Math.min(spans[0].start - 1, opts.headerLines);
+  if (headerEnd > 0) {
+    const header = raw.slice(0, headerEnd).filter((l) => l.trim());
+    if (header.length) parts.push(header.map((l, i) => String(i + 1).padStart(5) + " " + l).join("\n"));
+    if (spans[0].start - 1 > opts.headerLines) parts.push("      … " + (spans[0].start - 1 - opts.headerLines) + " more header lines");
+  }
+  for (let i = 0; i < spans.length; i++) parts.push(expanded.has(i) ? expandedBlock(spans[i], raw, opts) : foldedLine(spans[i]));
+  const title = "// " + relPath + " · " + lineCount + " lines · " + spans.length + " declarations · " + expanded.size + " expanded" + (about ? " for \"" + about + "\"" : "") + " · read(path, line, count) for a folded body";
+  return { text: title + "\n" + parts.join("\n"), expanded: expanded.size, declarations: spans.length };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "Dual-host CodeMode for Pi/OMP: progressive tool discovery, result bottleneck, and Amdahl Auto parallel.",
   "type": "module",
   "author": "AdityaVG13",
@@ -32,6 +32,11 @@
     "guest-worker.js",
     "repo-index.js",
     "evidence.js",
+    "fuzzy.js",
+    "outline.js",
+    "ledger.js",
+    "check.js",
+    "search.js",
     "format.js",
     "patch.js",
     "vfs.js",
@@ -85,5 +90,9 @@
   "bugs": {
     "url": "https://github.com/AdityaVG13/pi-stack/issues"
   },
-  "homepage": "https://github.com/AdityaVG13/pi-stack/tree/main/packages/pi-supernova#readme"
+  "homepage": "https://github.com/AdityaVG13/pi-stack/tree/main/packages/pi-supernova#readme",
+  "dependencies": {
+    "acorn": "^8.18.0",
+    "string-width": "^8.2.2"
+  }
 }