@codewithjuber/forgekit 0.8.0

package/src/anchor.js

@@ -0,0 +1,210 @@
+// forge anchor — M4 goal-anchoring (the paper's continuous goal-drift check, made
+// deterministic). Given the original objective, compare the files you've ACTUALLY
+// changed (git) against the area the goal named. Flags work that has wandered off it.
+// Advisory — a stated goal is re-read against real diffs, not trusted to stay in view.
+import { execFileSync } from "node:child_process";
+import { adjudicate, asText, buildRunner, llmEnabled } from "./adjudicate.js";
+import { load as loadAtlas, query as queryAtlas } from "./atlas.js";
+import { referencedEntities } from "./preflight.js";
+
+const STOP = new Set(
+  "the a an to of in on for and or add fix make use update change new it its into with from this that be is are so all any".split(
+    " ",
+  ),
+);
+
+function goalKeywords(goal) {
+  const { symbols, files } = referencedEntities(goal);
+  // Strip path/file tokens (src/auth.js) so their generic parts (src, js) don't become
+  // keywords that match every file — the files themselves are matched via goalTargetFiles.
+  const prose = String(goal)
+    .toLowerCase()
+    .replace(/\S*[/.]\S*/g, " ");
+  const words = prose.match(/[a-z][a-z0-9_-]{2,}/g) || [];
+  const keywords = new Set(words.filter((w) => !STOP.has(w)));
+  for (const s of symbols) keywords.add(s.toLowerCase());
+  return { keywords: [...keywords], symbols, files };
+}
+
+// Machine-generated / tool-config noise that isn't the developer's own work: forge's
+// cache and every config file `forge init` emits (dot-paths + AGENTS/CLAUDE).
+// ponytail: this also hides drift in genuine dot-dir edits (.github/*) — fine for an
+// advisory coarse check; widen to a managed-file manifest if that ever matters.
+const NOISE = /(^|\/)\.forge\/|(^|\/)\.[^/]+\/|^\.[^/]+$|(^|\/)(AGENTS|CLAUDE)\.md$/i;
+
+function gitFiles(root) {
+  const run = (args) => {
+    try {
+      return execFileSync("git", args, {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+    } catch {
+      return "";
+    }
+  };
+  const out =
+    run(["diff", "--name-only", "HEAD"]) + run(["ls-files", "--others", "--exclude-standard"]);
+  return [
+    ...new Set(
+      out
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    ),
+  ].filter((f) => !NOISE.test(f));
+}
+
+// Files the goal's named symbols actually live in, so a symbol-named goal anchors to its
+// file (e.g. "change verifyToken" anchors to src/auth.js, which the name alone wouldn't match).
+function goalTargetFiles(root, symbols, files) {
+  const targets = new Set(files.map((f) => f.replace(/^\.?\//, "")));
+  const atlas = loadAtlas(root);
+  if (atlas)
+    for (const s of symbols)
+      for (const hit of queryAtlas(atlas, s)) if (hit.name === s) targets.add(hit.file);
+  return [...targets];
+}
+
+// M4 goal-drift — LLM proposer. Semantically classifies the files the coarse keyword match
+// flagged as off-goal. PROPOSER ONLY, and one-directional: the model may only move a file
+// off→on (never on→off), and only with a reason that references the goal — so it can quiet a
+// false drift flag but can never hide a real one. Preserves the "errs toward on-goal" invariant.
+export function buildDriftPrompt(goal, offGoalFiles) {
+  const list = offGoalFiles
+    .slice(0, 40)
+    .map((f) => `- ${f}`)
+    .join("\n");
+  return `A developer's stated goal is: """${String(goal).slice(0, 400)}"""
+These changed files did NOT obviously match the goal by name:
+${list}
+For each, decide if the change is plausibly IN SERVICE of that goal. Answer with STRICT JSON and
+nothing else, listing only files from above that genuinely serve the goal:
+{"onGoal":[{"file":"<path>","reason":"<why it serves the goal>"}]}
+Omit files that do not serve the goal. No text outside the JSON object.`;
+}
+
+export function parseDriftProposal(obj) {
+  const onGoal = Array.isArray(obj.onGoal)
+    ? obj.onGoal
+        .map((e) => ({ file: asText(e?.file, 240), reason: asText(e?.reason, 200) }))
+        .filter((e) => e.file && e.reason)
+    : [];
+  return { onGoal };
+}
+
+export function driftLLM(goal, offGoalFiles, { run = buildRunner() } = {}) {
+  if (!offGoalFiles.length) return { onGoal: [] };
+  return adjudicate({
+    prompt: buildDriftPrompt(goal, offGoalFiles),
+    parse: parseDriftProposal,
+    run,
+  });
+}
+
+/**
+ * @param {string} root
+ * @param {string} goal
+ * @param {{ changed?: string[], llm?:boolean, run?:(p:string)=>string, model?:string, timeoutMs?:number }} [opts]
+ *   inject `changed` to skip git; inject `run` to stub the model (used in tests).
+ */
+export function goalDrift(root, goal, opts = {}) {
+  const { keywords, symbols, files } = goalKeywords(goal);
+  const changedFiles = opts.changed || gitFiles(root);
+  const targets = goalTargetFiles(root, symbols, files).map((t) => t.toLowerCase());
+  const onGoal = [];
+  const offGoal = [];
+  for (const f of changedFiles) {
+    const lf = f.toLowerCase();
+    // ponytail: path/keyword match, not semantic — coarse on purpose (are you in the
+    // right AREA?), and errs toward "on-goal" so it never cries drift on a match.
+    const named = targets.some((t) => lf === t || lf.endsWith(`/${t}`));
+    (named || keywords.some((k) => lf.includes(k)) ? onGoal : offGoal).push(f);
+  }
+
+  // Opt-in semantic pass: rescue files the keyword match missed, but only off→on and only when
+  // the model gives a goal-referencing reason. Verified, not trusted; fail-safe on any error.
+  let provenance = { path: "deterministic" };
+  if (llmEnabled({ llm: opts.llm }) && offGoal.length) {
+    const goalTerms = new Set([...keywords, ...symbols.map((s) => s.toLowerCase())]);
+    const grounded = (reason) => {
+      const words = String(reason).toLowerCase();
+      return goalTerms.size === 0 || [...goalTerms].some((t) => words.includes(t));
+    };
+    const proposal = driftLLM(goal, offGoal, {
+      run: opts.run || buildRunner({ model: opts.model, timeoutMs: opts.timeoutMs }),
+    });
+    const rescued = new Set(
+      (proposal?.onGoal || [])
+        .filter((e) => offGoal.includes(e.file) && grounded(e.reason))
+        .map((e) => e.file),
+    );
+    if (rescued.size) {
+      for (const f of [...offGoal]) {
+        if (rescued.has(f)) {
+          offGoal.splice(offGoal.indexOf(f), 1);
+          onGoal.push(f);
+        }
+      }
+      provenance = { path: "llm-verified", rescued: [...rescued] };
+    } else if (proposal) {
+      provenance = { path: "llm-agreed" };
+    }
+  }
+
+  const drift = changedFiles.length > 0 && (offGoal.length > 0 || onGoal.length === 0);
+  return {
+    goal: String(goal),
+    keywords,
+    changed: changedFiles,
+    onGoal,
+    offGoal,
+    drift,
+    provenance,
+  };
+}
+
+/**
+ * M4 — one-sided CUSUM control chart over a drift-signal series (spec §5:
+ * docs/plans/substrate-v2/06-faculties-and-mechanisms.md). A raw threshold on a
+ * single checkpoint's drift Dₜ is noisy — one exploratory step legitimately wanders.
+ * CUSUM accumulates only the excess over the allowance k (Cₜ = max(0, Cₜ₋₁ + Dₜ − k))
+ * and alarms at Cₜ > h, which detects SUSTAINED small drift with provably minimal
+ * detection delay for a given false-alarm rate (classical sequential analysis),
+ * while a single within-tolerance spike drains back to zero instead of alarming.
+ * Defaults k = 0.35, h = 1.0 per the spec (calibration lands in P8). Pure.
+ * @param {number[]} signals drift per checkpoint, Dₜ ∈ [0, 1] (non-numeric → 0)
+ * @param {{k?: number, h?: number}} [opts]
+ * @returns {{alarm: boolean, C: number[], firstAlarm: number}} firstAlarm = index of
+ *   the first checkpoint whose statistic crossed h, or -1 if none did.
+ */
+export function cusum(signals, { k = 0.35, h = 1.0 } = {}) {
+  const C = [];
+  let c = 0;
+  let firstAlarm = -1;
+  for (let i = 0; i < signals.length; i++) {
+    const d = Number(signals[i]);
+    c = Math.max(0, c + (Number.isFinite(d) ? d : 0) - k);
+    C.push(c);
+    if (firstAlarm < 0 && c > h) firstAlarm = i;
+  }
+  return { alarm: firstAlarm >= 0, C, firstAlarm };
+}
+
+export function renderAnchor(r) {
+  const lines = ["Forge anchor — goal-drift check", ""];
+  if (!r.changed.length)
+    return `${lines.join("\n")}\n  no changes yet vs HEAD — nothing to check against the goal.`;
+  lines.push(
+    `  changed: ${r.changed.length} file(s) · on-goal ${r.onGoal.length} · off-goal ${r.offGoal.length}`,
+  );
+  if (r.offGoal.length) {
+    lines.push("", "  off-goal (unrelated to the stated goal — intended, or drift?):");
+    for (const f of r.offGoal.slice(0, 12)) lines.push(`    - ${f}`);
+  }
+  if (r.drift && !r.offGoal.length)
+    lines.push("", "  ! no changed file matches the goal — are you working on the right thing?");
+  if (!r.drift) lines.push("", "  ✓ on goal — every change maps to what you set out to do.");
+  return lines.join("\n");
+}

package/src/atlas.js

@@ -0,0 +1,487 @@
+// forge atlas — a portable code graph. Build once, then query definitions, membership,
+// reverse dependents, and impact radius without asking a model to rediscover the repo.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+import { adjudicate, asText, buildRunner, llmEnabled } from "./adjudicate.js";
+import { CALL_RE } from "./extract.js";
+import { contentHash, IGNORE_DIRS } from "./util.js";
+
+const JS_RULES = [
+  { re: /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g, kind: "function" },
+  { re: /(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/g, kind: "class" },
+  { re: /(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g, kind: "const" },
+];
+const RULES = {
+  ".js": JS_RULES,
+  ".jsx": JS_RULES,
+  ".ts": JS_RULES,
+  ".tsx": JS_RULES,
+  ".mjs": JS_RULES,
+  ".cjs": JS_RULES,
+  ".py": [
+    { re: /^\s*def\s+([A-Za-z_]\w*)/gm, kind: "function" },
+    { re: /^\s*class\s+([A-Za-z_]\w*)/gm, kind: "class" },
+  ],
+  ".go": [
+    { re: /^func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)/gm, kind: "function" },
+    { re: /^type\s+([A-Za-z_]\w*)/gm, kind: "type" },
+  ],
+  ".rs": [
+    { re: /\bfn\s+([A-Za-z_]\w*)/g, kind: "function" },
+    { re: /\b(?:struct|enum|trait)\s+([A-Za-z_]\w*)/g, kind: "type" },
+  ],
+  ".java": [{ re: /\b(?:class|interface|enum)\s+([A-Za-z_]\w*)/g, kind: "type" }],
+};
+
+const IMPORT_RE =
+  /(?:import\s+(?:[^"'\n]+\s+from\s+)?["']([^"']+)["']|require\(["']([^"']+)["']\)|^\s*(?:from\s+([\w.]+)\s+)?import\s+([\w*,\s]+))/gm;
+const BUILTINS = new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "function",
+  "return",
+  "console",
+  "String",
+  "Number",
+  "Boolean",
+  "Array",
+  "Object",
+  "Promise",
+  "Set",
+  "Map",
+  "Date",
+  "Error",
+  "RegExp",
+  "parseInt",
+  "parseFloat",
+  "setTimeout",
+  "clearTimeout",
+  "fetch",
+  "print",
+  "len",
+  "range",
+  "int",
+  "str",
+  "float",
+  "dict",
+  "list",
+  "set",
+  "super",
+]);
+
+const hash = contentHash;
+
+function walk(dir, files, cap) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch (err) {
+    if (process.env.FORGE_DEBUG === "1")
+      process.stderr.write(`forge atlas: skipping ${dir}: ${err?.message ?? err}\n`);
+    return;
+  }
+  for (const name of entries) {
+    if (IGNORE_DIRS.has(name) || name.startsWith(".")) continue;
+    const path = join(dir, name);
+    let st;
+    try {
+      st = statSync(path);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) walk(path, files, cap);
+    else if (RULES[extname(name)] && files.length < cap) files.push(path);
+  }
+}
+
+function moduleId(rel) {
+  return rel.replace(/\.[^.]+$/, "").replace(/[/\\]/g, ".");
+}
+
+function lineOf(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+
+function nearestSource(nodes, line, fallback) {
+  let best = fallback;
+  for (const n of nodes) {
+    if (n.line <= line && (!best.line || n.line >= best.line)) best = n;
+  }
+  return best;
+}
+
+function extractFile(path, root, preRead) {
+  const ext = extname(path);
+  const rules = RULES[ext];
+  const rel = relative(root, path);
+  let text = preRead;
+  if (text == null) {
+    try {
+      text = readFileSync(path, "utf8");
+    } catch {
+      return { symbols: [], nodes: [], edges: [], hash: "" };
+    }
+  }
+
+  const mod = {
+    id: `module:${moduleId(rel)}`,
+    name: moduleId(rel),
+    kind: "module",
+    file: rel,
+    line: 1,
+  };
+  const symbols = [];
+  const nodes = [mod];
+  const edges = [];
+
+  for (const { re, kind } of rules) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+      const name = m[1];
+      const line = lineOf(text, m.index);
+      const node = {
+        id: `${rel}:${name}:${line}`,
+        qname: `${moduleId(rel)}.${name}`,
+        name,
+        kind,
+        file: rel,
+        line,
+      };
+      symbols.push({ name, kind, file: rel, line, id: node.id, qname: node.qname });
+      nodes.push(node);
+      edges.push({ source: mod.id, target: node.id, kind: "contains", confidence: 1, line });
+    }
+  }
+
+  // Inheritance edges — `class X extends Y` (JS/TS) and `class X(Base, …)` (Python). Without
+  // these the `inherits` edge weight was dead and a base-class change never appeared in blast
+  // radius. The base is a bare name; resolveEdges links it to a real node if one exists.
+  const classNodes = new Map(nodes.filter((n) => n.kind === "class").map((n) => [n.name, n]));
+  const INHERIT_RES = [
+    /\bclass\s+([A-Za-z_$][\w$]*)\s+extends\s+([A-Za-z_$][\w$.]*)/g, // JS/TS
+    /^\s*class\s+([A-Za-z_]\w*)\s*\(([^)]*)\)/gm, // Python
+  ];
+  for (const re of INHERIT_RES) {
+    re.lastIndex = 0;
+    let cm;
+    while ((cm = re.exec(text))) {
+      const child = classNodes.get(cm[1]);
+      if (!child) continue;
+      const line = lineOf(text, cm.index);
+      const bases = cm[2]
+        .split(",")
+        .map((b) => b.trim())
+        .filter((b) => b && !b.includes("=")) // drop Python kwargs like metaclass=ABCMeta
+        .map((b) => b.split(".").pop()) // module.Base → Base
+        .filter((b) => b && b !== cm[1] && b.toLowerCase() !== "object");
+      for (const base of bases)
+        edges.push({ source: child.id, target: base, kind: "inherits", confidence: 0.9, line });
+    }
+  }
+
+  IMPORT_RE.lastIndex = 0;
+  let im;
+  while ((im = IMPORT_RE.exec(text))) {
+    const target = im[1] || im[2] || im[3] || "";
+    const names = im[4]
+      ? im[4]
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    const line = lineOf(text, im.index);
+    const source = nearestSource(nodes.slice(1), line, mod);
+    if (target) edges.push({ source: source.id, target, kind: "imports", confidence: 0.85, line });
+    for (const name of names) {
+      if (name !== "*")
+        edges.push({
+          source: source.id,
+          target: target ? `${target}.${name}` : name,
+          kind: "imports",
+          confidence: 0.85,
+          line,
+        });
+    }
+  }
+
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineText = lines[index];
+    CALL_RE.lastIndex = 0;
+    const line = index + 1;
+    let cm;
+    while ((cm = CALL_RE.exec(lineText))) {
+      const callee = cm[1];
+      if (BUILTINS.has(callee)) continue;
+      const source = nearestSource(nodes.slice(1), line, mod);
+      if (source.name === callee) continue;
+      edges.push({ source: source.id, target: callee, kind: "calls", confidence: 0.75, line });
+    }
+  }
+
+  return { symbols, nodes, edges, hash: hash(text) };
+}
+
+function resolveEdges(nodes, edges) {
+  const byName = new Map();
+  const byQname = new Map();
+  const idSet = new Set();
+  for (const n of nodes) {
+    idSet.add(n.id);
+    if (n.name) {
+      const arr = byName.get(n.name) || [];
+      arr.push(n);
+      byName.set(n.name, arr);
+    }
+    if (n.qname) byQname.set(n.qname, n);
+  }
+  return edges.map((edge) => {
+    // O(1) membership — this was a full nodes.some() scan per edge (O(E·N) on real repos).
+    if (idSet.has(edge.target)) return edge;
+    const direct = byQname.get(edge.target);
+    if (direct) return { ...edge, target: direct.id, resolved: true };
+    const short = String(edge.target).split(".").pop();
+    const matches = byName.get(short) || [];
+    if (matches.length === 1)
+      return { ...edge, target: matches[0].id, resolved: true, confidence: edge.confidence * 0.9 };
+    return { ...edge, unresolved: true };
+  });
+}
+
+const cachePath = (root) => join(root, ".forge", "atlas.cache.json");
+
+function readCache(root) {
+  try {
+    return existsSync(cachePath(root)) ? JSON.parse(readFileSync(cachePath(root), "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function build({ root = process.cwd(), cap = 20000 } = {}) {
+  const files = [];
+  walk(root, files, cap);
+  // Incremental: reuse the prior per-file extraction when the content hash is unchanged, so a
+  // rebuild only re-parses edited files instead of re-running every regex over the whole repo.
+  const prev = readCache(root);
+  const cache = {};
+  const symbols = [];
+  const nodes = [];
+  const rawEdges = [];
+  const fileHashes = {};
+  for (const f of files) {
+    const rel = relative(root, f);
+    let text;
+    try {
+      text = readFileSync(f, "utf8");
+    } catch {
+      continue;
+    }
+    const h = hash(text);
+    const reused = prev[rel]?.hash === h ? prev[rel].data : null;
+    const data =
+      reused ||
+      (({ symbols, nodes, edges }) => ({ symbols, nodes, edges }))(extractFile(f, root, text));
+    cache[rel] = { hash: h, data };
+    symbols.push(...data.symbols);
+    nodes.push(...data.nodes);
+    rawEdges.push(...data.edges);
+    fileHashes[rel] = h;
+  }
+  const edges = resolveEdges(nodes, rawEdges);
+  const atlas = {
+    version: 2,
+    files: files.length,
+    symbols,
+    nodes,
+    edges,
+    fileHashes,
+    capped: files.length >= cap,
+  };
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(join(root, ".forge", "atlas.json"), JSON.stringify(atlas));
+  writeFileSync(cachePath(root), JSON.stringify(cache));
+  return atlas;
+}
+
+/** True if any tracked file's current content hash differs from the atlas (or a file vanished). */
+export function isStale(root, atlas) {
+  if (!atlas?.fileHashes) return true;
+  for (const [rel, h] of Object.entries(atlas.fileHashes)) {
+    let text;
+    try {
+      text = readFileSync(join(root, rel), "utf8");
+    } catch {
+      return true; // a tracked file was deleted
+    }
+    if (hash(text) !== h) return true;
+  }
+  return false;
+}
+
+export function load(root = process.cwd()) {
+  const p = join(root, ".forge", "atlas.json");
+  return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null;
+}
+
+export function query(atlas, term) {
+  const t = String(term).toLowerCase();
+  return (atlas.symbols || []).filter(
+    (s) =>
+      s.name.toLowerCase().includes(t) ||
+      String(s.qname || "")
+        .toLowerCase()
+        .includes(t),
+  );
+}
+
+export function has(atlas, name) {
+  return (atlas.symbols || []).some((s) => s.name === name || s.qname === name || s.id === name);
+}
+
+function targetIds(atlas, target) {
+  const t = String(target);
+  const nodes = atlas.nodes || [];
+  const matches = nodes.filter(
+    (n) => n.id === t || n.name === t || n.qname === t || n.file === t || n.file?.endsWith(`/${t}`),
+  );
+  return matches.map((n) => n.id);
+}
+
+const EDGE_WEIGHT = { calls: 0.95, imports: 0.85, inherits: 0.92, references: 0.7, contains: 0.45 };
+
+// Reverse-adjacency (node id → incoming edges) + node lookup, built once per atlas and memoized.
+// substrateCheck calls impact() up to 8× on the same atlas; without this each call rebuilt both.
+const ADJ_CACHE = new WeakMap();
+function adjacency(atlas) {
+  const cached = ADJ_CACHE.get(atlas);
+  if (cached) return cached;
+  const nodeById = new Map((atlas.nodes || []).map((n) => [n.id, n]));
+  const incoming = new Map();
+  for (const e of atlas.edges || []) {
+    if (e.unresolved) continue;
+    const arr = incoming.get(e.target) || [];
+    arr.push(e);
+    incoming.set(e.target, arr);
+  }
+  const built = { nodeById, incoming };
+  ADJ_CACHE.set(atlas, built);
+  return built;
+}
+
+// Imagination (§8) — LLM proposer for the edges the regex graph structurally misses: dynamic
+// dispatch, DI, reflection, string-keyed lookups. PROPOSER ONLY. Every candidate is then
+// verified twice — it must resolve to a REAL node in the graph AND (via the caller's `verify`
+// predicate, a grep) actually reference the target in source. Unverifiable → dropped, never added.
+export function buildImpactPrompt(atlas, target) {
+  const files = [...new Set((atlas.nodes || []).map((n) => n.file).filter(Boolean))].slice(0, 60);
+  return `A code symbol/file is about to change. Name the OTHER files in this repo that most
+likely break or depend on it through edges a regex misses: dynamic dispatch, dependency
+injection, reflection, string-keyed registries, event handlers.
+Changing target: ${String(target).slice(0, 120)}
+Files in repo:
+${files.map((f) => `- ${f}`).join("\n")}
+Answer with STRICT JSON and nothing else, listing only files from the list above:
+{"files":["<path>"...]}
+No text outside the JSON object.`;
+}
+
+export function parseImpactProposal(obj) {
+  const files = Array.isArray(obj.files)
+    ? [...new Set(obj.files.map((f) => asText(f, 240)).filter(Boolean))].slice(0, 20)
+    : [];
+  return { files };
+}
+
+export function impactLLM(atlas, target, { run = buildRunner() } = {}) {
+  return adjudicate({ prompt: buildImpactPrompt(atlas, target), parse: parseImpactProposal, run });
+}
+
+/**
+ * @param {object} atlas
+ * @param {string} target
+ * @param {object} [opts]
+ * @param {number} [opts.threshold]
+ * @param {number} [opts.maxHops]
+ * @param {number} [opts.decay]
+ * @param {boolean} [opts.llm]
+ * @param {(p:string)=>string} [opts.run]
+ * @param {(file:string, target:string)=>boolean} [opts.verify]
+ */
+export function impact(
+  atlas,
+  target,
+  { threshold = 0.1, maxHops = 6, decay = 0.85, llm, run, verify } = {},
+) {
+  const starts = targetIds(atlas, target);
+  const { nodeById, incoming } = adjacency(atlas);
+  const visited = new Map();
+  const queue = starts.map((id) => ({ id, confidence: 1, hop: 0, path: [id], edgeKinds: [] }));
+  while (queue.length) {
+    const current = queue.shift();
+    if (!current || current.hop >= maxHops) continue;
+    for (const edge of incoming.get(current.id) || []) {
+      if (starts.includes(edge.source)) continue;
+      const nextConfidence =
+        current.confidence * (EDGE_WEIGHT[edge.kind] || 0.5) * (edge.confidence ?? 1) * decay;
+      if (nextConfidence < threshold) continue;
+      const prev = visited.get(edge.source);
+      if (prev && prev.confidence >= nextConfidence) continue;
+      const item = {
+        id: edge.source,
+        node: nodeById.get(edge.source) || { id: edge.source, name: edge.source, kind: "unknown" },
+        confidence: Number(nextConfidence.toFixed(4)),
+        hopDistance: current.hop + 1,
+        path: [...current.path, edge.source],
+        edgeKinds: [...current.edgeKinds, edge.kind],
+      };
+      visited.set(edge.source, item);
+      queue.push({
+        id: edge.source,
+        confidence: nextConfidence,
+        hop: current.hop + 1,
+        path: item.path,
+        edgeKinds: item.edgeKinds,
+      });
+    }
+  }
+  const impacted = [...visited.values()].sort((a, b) => b.confidence - a.confidence);
+  const deterministicFiles = new Set(impacted.map((x) => x.node.file).filter(Boolean));
+
+  // Opt-in imagination pass: model proposes missed edges, but only VERIFIED ones are kept.
+  const llmImpacted = [];
+  if (llmEnabled({ llm }) && run) {
+    const knownFiles = new Set((atlas.nodes || []).map((n) => n.file).filter(Boolean));
+    const proposal = impactLLM(atlas, target, { run });
+    for (const file of proposal?.files || []) {
+      if (deterministicFiles.has(file)) continue; // already found deterministically
+      if (!knownFiles.has(file)) continue; // must be a real file in the graph
+      if (typeof verify === "function" && !verify(file, target)) continue; // must grep-confirm the ref
+      if (typeof verify !== "function") continue; // no external check available → never add blind
+      llmImpacted.push({
+        id: `llm:${file}`,
+        node: { id: `llm:${file}`, name: file, kind: "module", file },
+        confidence: Number((threshold * 0.9).toFixed(4)),
+        hopDistance: null,
+        source: "llm-verified",
+      });
+    }
+  }
+
+  const all = [...impacted, ...llmImpacted];
+  return {
+    target,
+    found: starts.length > 0,
+    threshold,
+    impacted: all,
+    impactedFiles: [...new Set(all.map((x) => x.node.file).filter(Boolean))].sort(),
+    llmVerified: llmImpacted.map((x) => x.node.file),
+    totalGraphNodes: (atlas.nodes || []).length,
+    totalGraphEdges: (atlas.edges || []).length,
+  };
+}