@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/chunk-ENW4BTBA.js

@@ -0,0 +1,930 @@
+import {
+  makeProvenance
+} from "./chunk-UUNHHX4M.js";
+import {
+  BrainDatabase
+} from "./chunk-QKTRECYS.js";
+import {
+  analysis_exclusions_exports
+} from "./chunk-SM7RFQRO.js";
+
+// src/intelligence/graph/line-address.ts
+var STORED_LINE_COLUMN = "r.line_number";
+var STORED_LINE_ALIAS = "bb_stored_call_line";
+var STORED_LINE_SELECT = `${STORED_LINE_COLUMN} AS ${STORED_LINE_ALIAS}`;
+var STORED_LINE_IS_EXACT_SQL = `typeof(${STORED_LINE_COLUMN}) = 'integer' AND ${STORED_LINE_COLUMN} > 0`;
+var STORED_LINE_IS_ABSENT_SQL = `(${STORED_LINE_COLUMN} IS NULL OR (typeof(${STORED_LINE_COLUMN}) = 'integer' AND ${STORED_LINE_COLUMN} = 0))`;
+function storedLineFromRow(row) {
+  if (row === null || row === void 0) return void 0;
+  return row[STORED_LINE_ALIAS];
+}
+var ADDRESS_NOTES = {
+  legacy: "call site not stored (legacy index: line_number is 0)",
+  notStored: "call site not stored (no line_number in the index)",
+  unusable: "call site not stored (unusable line_number in the index)",
+  substitute: "this is the calling symbol's declaration, not the call site",
+  /** L3's FOURTH reason, and it is not a store state: the store may well carry
+   *  the line — this surface could not read the ROW that carries it. The
+   *  distinct wording is load-bearing. A reader told "not stored" checks the
+   *  index; a reader told "could not be read" checks the walk that quoted the
+   *  evidence, and those are different investigations. Collapsing the two is
+   *  how a declared absence starts reading as a store fact. */
+  unattributed: "call site not read (no relationship row at this depth could be attributed)"
+};
+function classifyStoredLine(raw) {
+  if (raw === null || raw === void 0) return "not-stored";
+  if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw)) return "unusable";
+  if (raw > 0) return "real";
+  if (raw === 0) return "legacy-placeholder";
+  return "unusable";
+}
+function deriveCallSiteAddress(input) {
+  const file = typeof input.file === "string" ? input.file : "";
+  const state = classifyStoredLine(input.storedLine);
+  if (state === "real") {
+    return { kind: "call-site", file, line: input.storedLine };
+  }
+  const callerLine = input.callerDeclaration?.line;
+  if (state !== "unusable" && classifyStoredLine(callerLine) === "real") {
+    return { kind: "declaration", file, line: callerLine, note: ADDRESS_NOTES.substitute };
+  }
+  const note = state === "legacy-placeholder" ? ADDRESS_NOTES.legacy : state === "unusable" ? ADDRESS_NOTES.unusable : ADDRESS_NOTES.notStored;
+  return {
+    kind: "unknown",
+    file,
+    line: null,
+    note
+  };
+}
+function addressLine0(a) {
+  return a.kind === "call-site" ? a.line - 1 : null;
+}
+function isExactAddress(a) {
+  return a.kind === "call-site";
+}
+function unattributedAddress(file) {
+  return { kind: "unknown", file: typeof file === "string" ? file : "", line: null, note: ADDRESS_NOTES.unattributed };
+}
+
+// src/intelligence/graph/graph-engine.ts
+var DEFAULT_REL_TYPES = [
+  "calls",
+  "extends",
+  "implements",
+  "uses",
+  "instantiates",
+  "overrides",
+  "contains",
+  "references",
+  "imports",
+  "exports",
+  // EXTENDED 2026-10-18, and they MUST be appended here in the same change that makes analyzers emit
+  // them: this array is the default filter, so an unlisted kind is dropped BEFORE the query runs.
+  // The measured size of that mistake is in the block above (22.2% of every emitted relationship on
+  // a 1,200-file ruby sample) and it would be exactly 100% for the four new kinds, because they have
+  // no other route into a default traversal.
+  "decorates",
+  "renders",
+  "mixes_in",
+  "part_of"
+];
+function relationshipFilterReason(relTypes) {
+  return `relationshipTypes:${[...relTypes].sort().join("|")}`;
+}
+var DEFAULT_MAX_DEPTH = 5;
+var DEFAULT_BUDGET = 50;
+var DEFAULT_WALK_TIME_BUDGET_MS = 0;
+var EDGE_KIND_PRIORITY = {
+  // RENUMBERED 2026-10-18 to make room for the four extended kinds. The RELATIVE order of the ten is
+  // unchanged (calls < instantiates < extends < implements < overrides < uses < references < imports
+  // < exports < contains) — only the gaps are new, so no existing answer's ordering moves except
+  // where an extended kind is now in front of an old one (which is the point). The new kinds carry a
+  // dependency meaning and sit with the dependencies: `mixes_in` and `renders` compose a supertype /
+  // component (dependency), `decorates` applies a decorator to a declaration (dependency on the
+  // decorator), `part_of` is a compilation-unit inclusion (module-level, weakest for a traversal).
+  calls: 0,
+  instantiates: 2,
+  extends: 4,
+  implements: 6,
+  mixes_in: 7,
+  renders: 8,
+  overrides: 10,
+  decorates: 11,
+  uses: 12,
+  references: 14,
+  imports: 16,
+  exports: 18,
+  contains: 20,
+  part_of: 22
+};
+var UNRANKED_KIND_ORDER = 100;
+var KIND_RANK_SQL = (
+  // `r.relationship_type`, not `relType`: the CASE is evaluated against the
+  // FROM tables, and an output alias is not in scope there. Inside a compound
+  // select that is a hard error — "no such column: relType" — which the corpus
+  // suite found before any reasoning about it would have.
+  "CASE r.relationship_type " + Object.entries(EDGE_KIND_PRIORITY).map(([kind, rank]) => `WHEN '${kind}' THEN ${rank}`).join(" ") + ` ELSE ${UNRANKED_KIND_ORDER} END AS kindRank `
+);
+var DEFAULT_EDGE_QUERY_LIMIT = 200;
+var MAX_EDGE_QUERY_LIMIT = 5e3;
+var DEFAULT_MAX_TOTAL_EDGES = 1e3;
+var MAX_TOTAL_EDGES = 5e3;
+var MAX_TOTAL_COUNT_SCAN = 5e4;
+var STATEMENT_CACHE = /* @__PURE__ */ new WeakMap();
+function prepared(db, sql) {
+  let cache = STATEMENT_CACHE.get(db);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    STATEMENT_CACHE.set(db, cache);
+  }
+  let statement = cache.get(sql);
+  if (!statement) {
+    statement = db.prepare(sql);
+    cache.set(sql, statement);
+  }
+  return statement;
+}
+var EXTERNAL_ARM_SOURCE_INDEX = "brain_rel_proj_source_idx";
+var OWNER_RANGE_INDEXES = ["brain_symbol_project_owner_idx", "brain_symbol_owner_idx"];
+var SYMBOL_NAME_INDEX = "brain_sym_proj_name_idx";
+var indexPresence = /* @__PURE__ */ new WeakMap();
+function indexedBy(raw, indexName) {
+  if (raw === null || typeof raw !== "object") return "";
+  const db = raw;
+  if (typeof db.prepare !== "function") return "";
+  let presence = indexPresence.get(db);
+  if (presence === void 0) {
+    presence = /* @__PURE__ */ new Map();
+    indexPresence.set(db, presence);
+  }
+  let present = presence.get(indexName);
+  if (present === void 0) {
+    present = false;
+    try {
+      const rows = db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'index' AND name = ?").all(indexName);
+      present = rows.length > 0;
+    } catch {
+      present = false;
+    }
+    presence.set(indexName, present);
+  }
+  return present ? ` INDEXED BY ${indexName}` : "";
+}
+function externalArmIndexClause(raw) {
+  return indexedBy(raw, EXTERNAL_ARM_SOURCE_INDEX);
+}
+function cascadeBounds(symbolId) {
+  const prefix = symbolId.includes(":") ? symbolId.slice(0, symbolId.lastIndexOf(":") + 1) : "";
+  return { prefix, upper: prefix + ";" };
+}
+var CASCADE_INLINE_MAX = 400;
+function ownerRangeSeek(db) {
+  for (const index of OWNER_RANGE_INDEXES) {
+    const hint = indexedBy(db, index);
+    if (hint) return hint;
+  }
+  return "";
+}
+function cascadeIds(db, projectId, symbolId) {
+  try {
+    const { prefix, upper } = cascadeBounds(symbolId);
+    const ownerSeek = ownerRangeSeek(db);
+    const rows = prepared(
+      db,
+      `SELECT ? AS id UNION ALL SELECT m.id FROM brain_symbol m${ownerSeek} WHERE m.owner_symbol_id >= ? AND m.owner_symbol_id < ? AND m.project_id = ? LIMIT ?`
+    ).all(symbolId, prefix, upper, projectId, CASCADE_INLINE_MAX + 1);
+    if (rows.length > CASCADE_INLINE_MAX) return null;
+    return rows.map((row) => row.id);
+  } catch {
+    return null;
+  }
+}
+function cascadeInlineJoin(ids, column) {
+  const arms = ids.map(() => "SELECT ? AS id").join(" UNION ALL ");
+  return { sql: `JOIN (${arms}) casc ON casc.id = r.${column}`, params: ids };
+}
+function cascadeJoinFor(db, projectId, symbolId, column, cache) {
+  if (!cache.has(symbolId)) cache.set(symbolId, cascadeIds(db, projectId, symbolId));
+  const ids = cache.get(symbolId);
+  if (ids !== null && ids !== void 0) return cascadeInlineJoin(ids, column);
+  const { prefix, upper } = cascadeBounds(symbolId);
+  return {
+    sql: `JOIN (SELECT ? AS id UNION ALL SELECT m.id FROM brain_symbol m WHERE m.owner_symbol_id >= ? AND m.owner_symbol_id < ? AND m.project_id = ?) casc ON casc.id = r.${column}`,
+    params: [symbolId, prefix, upper, projectId]
+  };
+}
+function countUnattributedRows(db, projectId, rootId, relTypes, cascadeCache) {
+  try {
+    const relPlaceholders = relTypes.map(() => "?").join(",");
+    const callersJoin = cascadeJoinFor(db, projectId, rootId, "target_symbol_id", cascadeCache);
+    const callersRow = prepared(
+      db,
+      `SELECT COUNT(*) AS c FROM brain_relationship r
+        ${callersJoin.sql}
+       WHERE r.project_id = ? AND r.relationship_type IN (${relPlaceholders})
+         AND r.source_symbol_id IS NULL`
+    ).all(...callersJoin.params, projectId, ...relTypes)[0];
+    const calleesJoin = cascadeJoinFor(db, projectId, rootId, "source_symbol_id", cascadeCache);
+    const calleesRow = prepared(
+      db,
+      `SELECT COUNT(*) AS c FROM brain_relationship r
+        ${calleesJoin.sql}
+       WHERE r.project_id = ? AND r.relationship_type IN (${relPlaceholders})
+         AND r.source_symbol_id IS NOT NULL AND r.target_symbol_id IS NULL AND r.target_external IS NULL`
+    ).all(...calleesJoin.params, projectId, ...relTypes)[0];
+    return { callers: Number(callersRow?.c ?? 0), callees: Number(calleesRow?.c ?? 0) };
+  } catch {
+    return null;
+  }
+}
+function edgeMetadata(meta) {
+  if (!meta) return void 0;
+  try {
+    const parsed = JSON.parse(meta);
+    const out = {};
+    if (typeof parsed["evidenceClass"] === "string") out.evidenceClass = parsed["evidenceClass"];
+    if (typeof parsed["inferredAt"] === "number") {
+      out.enrichment = { inferredAt: parsed["inferredAt"] };
+      for (const key of ["role", "pattern", "layerFlow", "criticality", "frequency"]) {
+        if (typeof parsed[key] === "string") out.enrichment[key] = parsed[key];
+      }
+      for (const key of ["isTestCode", "isGeneratedCode", "isFrameworkContract", "isDependencyInjection"]) {
+        if (typeof parsed[key] === "boolean") out.enrichment[key] = parsed[key];
+      }
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function cascadeMatch(row, tracedId) {
+  return row.matchedId == null || row.matchedId === tracedId ? "exact" : "owner-cascade";
+}
+function matchedMember(row, tracedId) {
+  if (row.matchedId == null || row.matchedId === tracedId) return void 0;
+  if (!row.matchedName) return void 0;
+  return { name: row.matchedName, file: row.matchedFile || "" };
+}
+function nodeFromEdge(row) {
+  const external = !row.symId;
+  return {
+    id: row.symId || `ext:${row.extName || "unknown"}`,
+    name: row.symName || row.extName || "unknown",
+    symbolType: row.symType || (external ? "external" : "symbol"),
+    file: row.fileRel || "",
+    filePath: row.filePath || "",
+    line: row.line || 0,
+    lineEnd: row.lineEnd || 0,
+    language: row.fileLang || "unknown",
+    complexity: row.complexity || 0,
+    isExternal: external
+  };
+}
+async function traverseGraph(projectId, root, options = {}) {
+  const raw = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+  const maxDepth = Math.max(1, Math.min(Math.floor(options.maxDepth || DEFAULT_MAX_DEPTH), 10));
+  const relTypes = options.relationshipTypes?.length ? options.relationshipTypes : DEFAULT_REL_TYPES;
+  const callerFiltered = !!options.relationshipTypes?.length;
+  const relPlaceholders = relTypes.map(() => "?").join(",");
+  const edgeLimit = Math.max(1, Math.min(Math.floor(options.edgeLimit ?? DEFAULT_EDGE_QUERY_LIMIT), MAX_EDGE_QUERY_LIMIT));
+  const maxEdges = Math.max(1, Math.min(Math.floor(options.maxEdges ?? DEFAULT_MAX_TOTAL_EDGES), MAX_TOTAL_EDGES));
+  let totalLimitReached = false;
+  const CALLER_ORDER = "kindRank, fileRel, lineNumber, rowId";
+  const CALLEE_ORDER = "kindRank, fileRel, lineNumber, rowId";
+  const nodes = {};
+  let truncated = false;
+  const reasons = /* @__PURE__ */ new Set();
+  const noteReason = (reason) => {
+    reasons.add(reason);
+    truncated = true;
+  };
+  const timeBudgetMs = Math.max(0, Math.floor(options.timeBudgetMs ?? DEFAULT_WALK_TIME_BUDGET_MS));
+  const deadline = Date.now() + timeBudgetMs;
+  let timeBudgetExhausted = false;
+  const outOfTime = () => timeBudgetMs > 0 && Date.now() >= deadline;
+  const filterReason = callerFiltered ? relationshipFilterReason(relTypes) : null;
+  let maxDepthReached = 0;
+  let cappedQueries = 0;
+  let totalCallersIfKnown = null;
+  let totalCalleesIfKnown = null;
+  let totalsAreLowerBounds = false;
+  let noiseFilteredCallers = 0;
+  let noiseFilteredCallees = 0;
+  let crossLangExcludedCallers = 0;
+  let crossLangExcludedCallees = 0;
+  const survivesFilters = (row, name, includeCrossLanguage2) => {
+    if (!name || analysis_exclusions_exports.isNoiseSymbolName(name)) return false;
+    if (row.fileRel && analysis_exclusions_exports.isHardNoisePath(row.fileRel)) return false;
+    if (includeCrossLanguage2 === false && row.isCrossLang) return false;
+    return true;
+  };
+  const includeCrossLanguage = options.includeCrossLanguage !== false;
+  const countSurviving = (sqlWithoutLimit, params, nameOf) => {
+    let total = 0;
+    const scanned = prepared(raw, sqlWithoutLimit + " LIMIT ?").all(...params, MAX_TOTAL_COUNT_SCAN);
+    for (const row of scanned) {
+      if (survivesFilters(row, nameOf(row), includeCrossLanguage)) total++;
+    }
+    if (total >= MAX_TOTAL_COUNT_SCAN) totalsAreLowerBounds = true;
+    return total;
+  };
+  const matchedIdentities = /* @__PURE__ */ new Map();
+  const cascadeCache = /* @__PURE__ */ new Map();
+  const attachMatchedIdentities = (rows, tracedId) => {
+    const wanted = [];
+    for (const row of rows) {
+      const id = row.matchedId;
+      if (id == null || id === tracedId || matchedIdentities.has(id)) continue;
+      if (!wanted.includes(id)) wanted.push(id);
+    }
+    if (wanted.length === 0) return;
+    for (let i = 0; i < wanted.length; i += 400) {
+      const chunk = wanted.slice(i, i + 400);
+      const got = prepared(
+        raw,
+        "SELECT s.id AS id, s.name AS name, f.relative_path AS file FROM brain_symbol s LEFT JOIN brain_file f ON f.id = s.file_id WHERE s.id IN (" + chunk.map(() => "?").join(",") + ")"
+      ).all(...chunk);
+      for (const g of got) matchedIdentities.set(g.id, { name: g.name, file: g.file || "" });
+    }
+    for (const row of rows) {
+      const id = row.matchedId;
+      if (id == null) continue;
+      const hit = matchedIdentities.get(id);
+      if (hit) {
+        row.matchedName = hit.name;
+        row.matchedFile = hit.file;
+      }
+    }
+  };
+  const registerNode = (node) => {
+    if (!nodes[node.id]) nodes[node.id] = node;
+  };
+  registerNode({
+    id: root.id,
+    name: root.name,
+    symbolType: root.symbolType,
+    file: root.relativePath,
+    filePath: root.filePath,
+    line: root.line,
+    lineEnd: root.lineEnd,
+    language: root.language,
+    complexity: root.complexity,
+    isExternal: false
+  });
+  const emittedCallerRows = /* @__PURE__ */ new Set();
+  const emittedCallerSites = /* @__PURE__ */ new Set();
+  const emittedCalleeRows = /* @__PURE__ */ new Set();
+  const emittedCalleeSites = /* @__PURE__ */ new Set();
+  let collapsedCascadeRepeats = 0;
+  let collapsedSpellingVariants = 0;
+  let exactCallers = 0;
+  let cascadedCallers = 0;
+  let exactCallees = 0;
+  let cascadedCallees = 0;
+  let deeperCallers = 0;
+  let deeperCallees = 0;
+  let callerBudgetExhausted = false;
+  let calleeBudgetExhausted = false;
+  let edgesInBothDirections = 0;
+  const callers = [];
+  const visitedCallers = /* @__PURE__ */ new Set();
+  let callerBudget = options.callerBudget ?? DEFAULT_BUDGET;
+  const traceCallers = (symbolId, depth) => {
+    if (depth >= maxDepth || visitedCallers.has(symbolId)) return;
+    if (outOfTime()) {
+      timeBudgetExhausted = true;
+      noteReason("walk-time-budget-exhausted");
+      return;
+    }
+    visitedCallers.add(symbolId);
+    const callerCascade = cascadeJoinFor(raw, projectId, symbolId, "target_symbol_id", cascadeCache);
+    const callerSql = "SELECT r.id AS rowId, r.line_number AS lineNumber, r.relationship_type AS relType, r.confidence AS confidence, r.is_cross_language AS isCrossLang, r.bridge_mechanism AS bridge, r.metadata AS meta, s.id AS symId, s.name AS symName, s.line_start AS line, s.line_end AS lineEnd, s.complexity AS complexity, s.symbol_type AS symType, f.relative_path AS fileRel, f.path AS filePath, f.language AS fileLang, f.relative_path AS srcFileRel, NULL AS extName, r.target_basis AS targetBasis, casc.id AS matchedId, " + KIND_RANK_SQL + "FROM brain_relationship r JOIN brain_symbol s ON s.id = r.source_symbol_id AND s.project_id = r.project_id JOIN brain_file f ON f.id = s.file_id " + // A JOIN, not `target_symbol_id IN (cascade)`. The IN form filters
+    // correctly but discards WHICH id matched, and that is the only thing
+    // separating "someone calls Command" from "someone calls
+    // Command.Execute, attributed to its owner". The join is over the
+    // cascade's own ID LIST (see cascadeJoinFor), so `casc.id` is still the
+    // id that matched while the statement no longer re-materialises the
+    // owner range.
+    callerCascade.sql + " WHERE r.project_id = ? AND r.relationship_type IN (" + relPlaceholders + ")";
+    const callerParams = [...callerCascade.params, projectId, ...relTypes];
+    const fetched = prepared(raw, callerSql + " ORDER BY " + CALLER_ORDER + " LIMIT ?").all(
+      ...callerParams,
+      edgeLimit + 1
+    );
+    const capped = fetched.length > edgeLimit;
+    const rows = capped ? fetched.slice(0, edgeLimit) : fetched;
+    attachMatchedIdentities(rows, symbolId);
+    if (capped) {
+      cappedQueries++;
+      noteReason(depth === 0 ? "caller-site-limit" : "caller-site-limit-at-depth");
+      if (depth === 0 && totalCallersIfKnown === null && !outOfTime()) {
+        totalCallersIfKnown = countSurviving(callerSql + " ORDER BY " + CALLER_ORDER, callerParams, (r) => r.symName);
+      }
+    }
+    const children = [];
+    for (const row of rows) {
+      if (!row.symName || analysis_exclusions_exports.isNoiseSymbolName(row.symName)) {
+        noiseFilteredCallers++;
+        continue;
+      }
+      if (row.fileRel && analysis_exclusions_exports.isHardNoisePath(row.fileRel)) {
+        noiseFilteredCallers++;
+        continue;
+      }
+      if (options.includeCrossLanguage === false && row.isCrossLang) {
+        crossLangExcludedCallers++;
+        continue;
+      }
+      if (callers.length + callees.length >= maxEdges) {
+        totalLimitReached = true;
+        noteReason("total-edge-limit");
+        break;
+      }
+      if (emittedCallerRows.has(row.rowId)) {
+        collapsedCascadeRepeats++;
+        continue;
+      }
+      emittedCallerRows.add(row.rowId);
+      if (row.lineNumber != null && row.lineNumber > 0) {
+        const siteKey = `${row.relType}|${row.symId ?? ""}|${row.matchedId ?? symbolId}|${row.srcFileRel ?? ""}|${row.lineNumber}`;
+        if (emittedCallerSites.has(siteKey)) {
+          collapsedSpellingVariants++;
+          continue;
+        }
+        emittedCallerSites.add(siteKey);
+      }
+      if (depth > 0) deeperCallers++;
+      else if (cascadeMatch(row, symbolId) === "exact") exactCallers++;
+      else cascadedCallers++;
+      const node = nodeFromEdge(row);
+      registerNode(node);
+      callers.push({
+        from: node.id,
+        to: symbolId,
+        relationshipType: row.relType,
+        confidence: row.confidence ?? 0,
+        isCrossLanguage: !!row.isCrossLang,
+        bridgeMechanism: row.bridge || void 0,
+        // The address owner decides what this position
+        // IS. A stored line of 0 (the indexer's legacy literal) or NULL is
+        // NOT a position — the calling symbol's declaration is only ever a
+        // LABELED substitute, never silently presented as the call site.
+        callSite: deriveCallSiteAddress({
+          storedLine: row.lineNumber,
+          file: row.srcFileRel || node.file,
+          callerDeclaration: { line: node.line }
+        }),
+        depth,
+        rowId: row.rowId,
+        // Whether the stored row names the traced symbol or one of its
+        // members. Without it, a class with 180 methods answers every caller
+        // question as if all 180 methods were the class.
+        targetMatch: cascadeMatch(row, symbolId),
+        targetBasis: row.targetBasis === "symbol" || row.targetBasis === "external" || row.targetBasis === "unresolved" ? row.targetBasis : null,
+        matchedMember: matchedMember(row, symbolId),
+        metadata: edgeMetadata(row.meta)
+      });
+      maxDepthReached = Math.max(maxDepthReached, depth);
+      if (row.symId) children.push(row.symId);
+    }
+    for (const childId of children) {
+      if (visitedCallers.has(childId)) continue;
+      if (callerBudget <= 0) {
+        if (children.some((c) => !visitedCallers.has(c))) {
+          noteReason("caller-budget-exhausted");
+          callerBudgetExhausted = true;
+        }
+        break;
+      }
+      if (depth >= maxDepth - 1) {
+        if (children.some((c) => !visitedCallers.has(c))) noteReason("caller-depth-cap-reached");
+        break;
+      }
+      callerBudget--;
+      traceCallers(childId, depth + 1);
+    }
+  };
+  const callees = [];
+  const visitedCallees = /* @__PURE__ */ new Set();
+  let calleeBudget = options.calleeBudget ?? DEFAULT_BUDGET;
+  const traceCallees = (symbolId, srcFileRel, srcLine, depth) => {
+    if (depth >= maxDepth || visitedCallees.has(symbolId)) return;
+    if (outOfTime()) {
+      timeBudgetExhausted = true;
+      noteReason("walk-time-budget-exhausted");
+      return;
+    }
+    visitedCallees.add(symbolId);
+    const isExternal = symbolId.startsWith("ext:");
+    const calleeCascade = isExternal ? null : cascadeJoinFor(raw, projectId, symbolId, "source_symbol_id", cascadeCache);
+    const selectCols = "SELECT r.id AS rowId, r.line_number AS lineNumber, r.relationship_type AS relType, r.confidence AS confidence, r.is_cross_language AS isCrossLang, r.bridge_mechanism AS bridge, r.metadata AS meta, s.id AS symId, s.name AS symName, s.line_start AS line, s.line_end AS lineEnd, s.complexity AS complexity, s.symbol_type AS symType, f.relative_path AS fileRel, f.path AS filePath, f.language AS fileLang, src.relative_path AS srcFileRel, r.target_external AS extName, r.target_basis AS targetBasis, casc.id AS matchedId, " + KIND_RANK_SQL;
+    const selectColsUnresolved = "SELECT r.id AS rowId, r.line_number AS lineNumber, r.relationship_type AS relType, r.confidence AS confidence, r.is_cross_language AS isCrossLang, r.bridge_mechanism AS bridge, r.metadata AS meta, NULL AS symId, NULL AS symName, NULL AS line, NULL AS lineEnd, NULL AS complexity, NULL AS symType, NULL AS fileRel, NULL AS filePath, NULL AS fileLang, src.relative_path AS srcFileRel, r.target_external AS extName, r.target_basis AS targetBasis, casc.id AS matchedId, " + KIND_RANK_SQL;
+    let rows;
+    if (isExternal) {
+      rows = [];
+    } else {
+      const calleeSql = selectCols + "FROM brain_relationship r JOIN brain_symbol s ON s.id = r.target_symbol_id AND s.project_id = r.project_id JOIN brain_file f ON f.id = s.file_id LEFT JOIN brain_symbol srcsym ON srcsym.id = r.source_symbol_id LEFT JOIN brain_file src ON src.id = srcsym.file_id " + calleeCascade.sql + " WHERE r.project_id = ? AND r.relationship_type IN (" + relPlaceholders + ") AND r.target_symbol_id IS NOT NULL UNION ALL " + // The UNRESOLVED arm. `target_symbol_id IS NULL` is the store saying
+      // it could not resolve this target, and `target_external` is the NAME
+      // it saw — not an identity.
+      //
+      // This arm used to JOIN brain_symbol back on that name, which turned
+      // the admission into a claim. Measured on real corpora, the name it
+      // joined on is not even close to unique: vscode fans a single stored
+      // row out to 37,876 internal symbols for the name `match`, svelte to
+      // 437,570 for `end`. The tool then emitted those as edges — asked
+      // about typescript's `pseudoTypeEquivalentToType` it reported 27
+      // internal callees, the first of them `isErrorType` in a different
+      // file, when the stored row names `getTypeOfSymbol`. No such
+      // relationship exists.
+      //
+      // Three harms, one JOIN: fabricated edges; the 200-row cap consumed
+      // entirely by fan-out so real callees never appear (and
+      // `calleesIfUncapped` reporting the inflated number); and
+      // `children.push` recursing into the arbitrary match, contaminating
+      // everything downstream.
+      //
+      // An unresolved target is therefore reported as the `ext:<name>` node
+      // this contract already documents for it. The name is kept — it is
+      // the node's name — so nothing is lost; it is simply labelled for
+      // what it is.
+      selectColsUnresolved + "FROM brain_relationship r" + externalArmIndexClause(raw) + " LEFT JOIN brain_symbol srcsym ON srcsym.id = r.source_symbol_id LEFT JOIN brain_file src ON src.id = srcsym.file_id " + calleeCascade.sql + " WHERE r.project_id = ? AND r.relationship_type IN (" + relPlaceholders + ") AND r.target_symbol_id IS NULL AND r.target_external IS NOT NULL";
+      const calleeParams = [
+        ...calleeCascade.params,
+        projectId,
+        ...relTypes,
+        ...calleeCascade.params,
+        projectId,
+        ...relTypes
+      ];
+      const calleeOrder = " ORDER BY " + CALLEE_ORDER;
+      const fetched = prepared(raw, calleeSql + calleeOrder + " LIMIT ?").all(...calleeParams, edgeLimit + 1);
+      const capped = fetched.length > edgeLimit;
+      rows = capped ? fetched.slice(0, edgeLimit) : fetched;
+      attachMatchedIdentities(rows, symbolId);
+      if (capped) {
+        cappedQueries++;
+        noteReason(depth === 0 ? "callee-site-limit" : "callee-site-limit-at-depth");
+        if (depth === 0 && totalCalleesIfKnown === null && !outOfTime()) {
+          totalCalleesIfKnown = countSurviving(calleeSql + calleeOrder, calleeParams, (r) => r.symName || r.extName);
+        }
+      }
+    }
+    const children = [];
+    for (const row of rows) {
+      const targetName = row.symName || row.extName || "";
+      if (!targetName || analysis_exclusions_exports.isNoiseSymbolName(targetName)) {
+        noiseFilteredCallees++;
+        continue;
+      }
+      if (row.fileRel && analysis_exclusions_exports.isHardNoisePath(row.fileRel)) {
+        noiseFilteredCallees++;
+        continue;
+      }
+      if (options.includeCrossLanguage === false && row.isCrossLang) {
+        crossLangExcludedCallees++;
+        continue;
+      }
+      if (callers.length + callees.length >= maxEdges) {
+        totalLimitReached = true;
+        noteReason("total-edge-limit");
+        break;
+      }
+      if (emittedCalleeRows.has(row.rowId)) {
+        collapsedCascadeRepeats++;
+        continue;
+      }
+      emittedCalleeRows.add(row.rowId);
+      if (row.lineNumber != null && row.lineNumber > 0) {
+        const calleeKey = `${row.relType}|${row.matchedId ?? symbolId}|${row.symId ?? `ext:${row.extName ?? ""}`}|${row.srcFileRel ?? ""}|${row.lineNumber}`;
+        if (emittedCalleeSites.has(calleeKey)) {
+          collapsedSpellingVariants++;
+          continue;
+        }
+        emittedCalleeSites.add(calleeKey);
+      }
+      if (depth > 0) deeperCallees++;
+      else if (cascadeMatch(row, symbolId) === "exact") exactCallees++;
+      else cascadedCallees++;
+      const node = nodeFromEdge(row);
+      registerNode(node);
+      callees.push({
+        from: symbolId,
+        to: node.id,
+        relationshipType: row.relType,
+        confidence: row.confidence ?? 0,
+        isCrossLanguage: !!row.isCrossLang,
+        bridgeMechanism: row.bridge || void 0,
+        // Same rule as the callers side — the calling
+        // symbol's declaration (srcLine) is a labeled substitute only.
+        callSite: deriveCallSiteAddress({
+          storedLine: row.lineNumber,
+          file: row.srcFileRel || srcFileRel,
+          callerDeclaration: { line: srcLine }
+        }),
+        depth,
+        rowId: row.rowId,
+        sourceMatch: cascadeMatch(row, symbolId),
+        targetBasis: row.targetBasis === "symbol" || row.targetBasis === "external" || row.targetBasis === "unresolved" ? row.targetBasis : null,
+        matchedMember: matchedMember(row, symbolId),
+        metadata: edgeMetadata(row.meta)
+      });
+      maxDepthReached = Math.max(maxDepthReached, depth);
+      if (row.symId) children.push({ id: row.symId, file: node.file, line: node.line });
+    }
+    for (const child of children) {
+      if (visitedCallees.has(child.id)) continue;
+      if (calleeBudget <= 0) {
+        if (children.some((c) => !visitedCallees.has(c.id))) {
+          noteReason("callee-budget-exhausted");
+          calleeBudgetExhausted = true;
+        }
+        break;
+      }
+      if (depth >= maxDepth - 1) {
+        if (children.some((c) => !visitedCallees.has(c.id))) noteReason("callee-depth-cap-reached");
+        break;
+      }
+      calleeBudget--;
+      traceCallees(child.id, child.file, child.line, depth + 1);
+    }
+  };
+  if (options.direction !== "callees") traceCallers(root.id, 0);
+  if (options.direction !== "callers") traceCallees(root.id, root.relativePath, root.line, 0);
+  for (const edge of callers) {
+    if (emittedCalleeRows.has(edge.rowId)) edgesInBothDirections++;
+  }
+  const edgesByType = {};
+  for (const edge of [...callers, ...callees]) {
+    edgesByType[edge.relationshipType] = (edgesByType[edge.relationshipType] ?? 0) + 1;
+  }
+  return {
+    callers,
+    callees,
+    nodes,
+    truncated,
+    truncationReason: reasons.size > 0 ? [...reasons].join("+") : void 0,
+    truncationReasons: [...reasons],
+    filterNarrowed: filterReason !== null,
+    filterReason,
+    maxDepthReached,
+    maxDepth,
+    timeBudgetMs,
+    timeBudgetExhausted,
+    noiseFiltered: { callers: noiseFilteredCallers, callees: noiseFilteredCallees },
+    unattributed: countUnattributedRows(raw, projectId, root.id, relTypes, cascadeCache),
+    crossLanguageExcluded: { callers: crossLangExcludedCallers, callees: crossLangExcludedCallees },
+    edgeLimit,
+    maxEdges,
+    totalEdgeLimitReached: totalLimitReached,
+    cappedQueries,
+    totalCallersIfKnown,
+    totalCalleesIfKnown,
+    totalsAreLowerBounds,
+    exactCallers,
+    cascadedCallers,
+    exactCallees,
+    cascadedCallees,
+    deeperCallers,
+    deeperCallees,
+    callerBudget: options.callerBudget ?? DEFAULT_BUDGET,
+    calleeBudget: options.calleeBudget ?? DEFAULT_BUDGET,
+    callerBudgetExhausted,
+    calleeBudgetExhausted,
+    edgesInBothDirections,
+    edgesByType,
+    edgeKindPriority: [...Object.keys(EDGE_KIND_PRIORITY)],
+    relationshipTypesUsed: relTypes,
+    dedupedAtToolLayer: {
+      cascadeRepeatsCollapsed: collapsedCascadeRepeats,
+      spellingVariantsCollapsed: collapsedSpellingVariants
+    }
+  };
+}
+async function resolveGraphRootDetailed(projectId, name) {
+  const raw = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+  const STRUCTURAL = "('function','method','class','interface','trait','struct','enum','macro')";
+  const baseFor = (symbolHint) => "SELECT s.id, s.name, s.symbol_type AS symbolType, COALESCE(s.line_start,0) AS line, COALESCE(s.line_end,0) AS lineEnd, f.relative_path AS relativePath, f.path AS filePath, COALESCE(f.language,'unknown') AS language, COALESCE(s.complexity,0) AS complexity FROM brain_symbol s" + symbolHint + " JOIN brain_file f ON f.id = s.file_id AND f.project_id = s.project_id WHERE s.project_id = ? ";
+  const base = baseFor("");
+  const exactBase = baseFor(indexedBy(raw, SYMBOL_NAME_INDEX));
+  const RANK = " ORDER BY s.gravity_score DESC, s.id ASC LIMIT 1";
+  const exactStructural = exactBase + `AND s.symbol_type IN ${STRUCTURAL} AND s.name = ?`;
+  const exactAnyKind = exactBase + "AND s.name = ?";
+  const fuzzyStructural = base + `AND s.symbol_type IN ${STRUCTURAL} AND s.name LIKE ? ESCAPE '\\'`;
+  let match = "exact";
+  let predicate = exactStructural;
+  let param = name;
+  let rows = raw.prepare(exactStructural + RANK).all(projectId, name);
+  if (rows.length === 0) {
+    rows = raw.prepare(exactAnyKind + RANK).all(projectId, name);
+    predicate = exactAnyKind;
+    param = name;
+    match = "exact-any-kind";
+  }
+  if (rows.length === 0) {
+    const pattern = likeContains(name);
+    rows = raw.prepare(fuzzyStructural + RANK).all(projectId, pattern);
+    predicate = fuzzyStructural;
+    param = pattern;
+    match = "containment";
+  }
+  const root = rows[0] ?? null;
+  if (!root) return { root: null, candidates: 0, match: null };
+  const countRow = raw.prepare("SELECT COUNT(*) c FROM (" + predicate + ")").get(projectId, param);
+  return { root, candidates: Math.max(1, Number(countRow?.c ?? 1)), match };
+}
+function likeContains(needle) {
+  let escaped = "";
+  for (const ch of needle) {
+    if (ch === "\\" || ch === "%" || ch === "_") escaped += "\\" + ch;
+    else escaped += ch;
+  }
+  return `%${escaped}%`;
+}
+async function resolveGraphRoot(projectId, name) {
+  return (await resolveGraphRootDetailed(projectId, name)).root;
+}
+async function graphTraversal(projectId, name, options = {}) {
+  const { root, candidates, match } = await resolveGraphRootDetailed(projectId, name);
+  if (!root) throw new Error(`Symbol '${name}' not found`);
+  const {
+    callers,
+    callees,
+    nodes,
+    truncated,
+    truncationReason,
+    truncationReasons,
+    filterNarrowed,
+    filterReason,
+    maxDepthReached,
+    maxDepth,
+    timeBudgetMs,
+    timeBudgetExhausted,
+    noiseFiltered,
+    unattributed,
+    crossLanguageExcluded,
+    edgeLimit,
+    maxEdges,
+    totalEdgeLimitReached: totalLimitReached,
+    cappedQueries,
+    totalCallersIfKnown,
+    totalCalleesIfKnown,
+    totalsAreLowerBounds,
+    exactCallers,
+    cascadedCallers,
+    exactCallees,
+    cascadedCallees,
+    deeperCallers,
+    deeperCallees,
+    callerBudget,
+    calleeBudget,
+    callerBudgetExhausted,
+    calleeBudgetExhausted,
+    edgesInBothDirections,
+    edgesByType,
+    edgeKindPriority,
+    relationshipTypesUsed,
+    dedupedAtToolLayer
+  } = await traverseGraph(projectId, root, options);
+  const rootNode = nodes[root.id];
+  const crossLanguageEdges = [...callers, ...callees].filter((e) => e.isCrossLanguage).length;
+  return {
+    root: rootNode,
+    rootCandidates: candidates,
+    // WHICH step found the root, beside the root itself. Without this a
+    // containment match is indistinguishable from the symbol that was asked
+    // for, and the whole answer is confidently about the wrong symbol.
+    rootMatch: match,
+    callers,
+    callees,
+    nodes,
+    provenance: makeProvenance({
+      evidenceClass: "inferred",
+      engine: "graph@intelligence",
+      engineVersion: "m10.02",
+      projectId,
+      source: "brain_relationship",
+      limitations: [
+        "Traversal is bounded and unresolved external nodes cannot be recursively traversed.",
+        // WHY the whole answer is `inferred` while single edges can be
+        // `structural` — stated, not left to convention.
+        // The provenance class describes the ANSWER, and the answer is a
+        // construction over stored rows: the root is picked by a gravity
+        // tie-break (or a containment fallback), the owner cascade attributes
+        // member rows to an owner, a noise policy removes rows, and any cap
+        // makes the edge set a prefix. The class of a construction is the
+        // weakest part of it, so `inferred` is correct here and the per-row
+        // evidence class lives on each edge's own `tier`/`confidence`.
+        "provenance.evidenceClass is `inferred` for the ANSWER, not for every edge: root resolution, the owner cascade, the noise policy and any cap are constructions over stored rows, so the whole object cannot claim `structural` even when each returned edge carries a stored row. Per-row evidence is on `edge.tier` (a stored `calls` row is `structural`)."
+      ],
+      truncated,
+      unknowns: [
+        ...noiseFiltered.callers + noiseFiltered.callees > 0 ? [`noise-policy: ${noiseFiltered.callers} caller and ${noiseFiltered.callees} callee stored rows were removed because they live in a vendored, generated, fixture, snapshot, dist or build path, or carry a generated name. They are excluded by POLICY, not absent: an empty edge set here does not mean nothing references this symbol. Applies to bb_search, bb_impact and the test-intelligence modes too, and NOT to mode "complexity", which applies no noise filter \u2014 so the same symbol can be unmeasurable there and unmentioned here.`] : [],
+        ...unattributed == null ? [`unattributed-source: the count of stored rows naming this symbol with no resolvable SOURCE could not be taken, so this answer cannot say whether such rows exist. It is NOT zero \u2014 the field is null for that reason.`] : unattributed.callers + unattributed.callees > 0 ? [`unattributed-source: ${unattributed.callers} caller and ${unattributed.callees} callee stored rows name this symbol (or a member of its owner cascade) but carry no source symbol, so no traversal can show them in either direction. They are counted, not listed \u2014 the rows exist and name this symbol; treating the edge sets above as the whole set would understate it. Depth-0 only: deeper symbols report their own edges, not their own unattributed rows. Remediation, if the count matters: a full re-index (the bb index command) is what re-attributes sources; a changed-only run does not re-parse the files those rows came from.`] : [],
+        ...crossLanguageExcluded.callers + crossLanguageExcluded.callees > 0 ? [`cross-language-scope: ${crossLanguageExcluded.callers} caller and ${crossLanguageExcluded.callees} callee stored rows were removed because this call passed includeCrossLanguage: false. The rows are stored and resolvable; they are excluded BY REQUEST, so this answer is a subset rather than the whole set. Re-run with includeCrossLanguage: true (the default) for the complete edge sets.`] : []
+      ]
+    }),
+    summary: {
+      totalCallers: callers.length,
+      totalCallees: callees.length,
+      maxDepthReached,
+      maxDepth,
+      timeBudgetMs,
+      timeBudgetExhausted,
+      // How many stored rows the vendored/generated/fixture/noise policy removed
+      // before any bound applied. Non-zero means the edge sets above are
+      // smaller than the store's, BY POLICY — not because nothing was found.
+      noiseFiltered,
+      // The JOIN's blind spot, counted: rows naming this symbol with no source to
+      // attach them to. `null` = not counted, never zero. See the field's own
+      // comment on `GraphTraversalSummary`.
+      unattributed,
+      // Rows the includeCrossLanguage scope option removed. A REQUEST, not a
+      // policy or a bound, and now a number rather than an inference from
+      // `crossLanguageEdges: 0`.
+      crossLanguageExcluded,
+      crossLanguageEdges,
+      truncated,
+      truncationReason,
+      // D10: the reasons as data, beside the `+`-joined string. Both are
+      // published: the string is what existing consumers parse, and the list is
+      // what a reason containing `+` cannot corrupt.
+      truncationReasons,
+      // D5: the filter, in its own channel. `truncated` above now means ONLY
+      // "a declared bound bit", so `truncated: false` beside
+      // `filterNarrowed: true` reads correctly: the walk finished, and the
+      // question it answered was a subset the caller asked for.
+      filterNarrowed,
+      filterReason,
+      // `totalCallers`/`totalCallees` above are the RETURNED
+      // counts. These fields say so explicitly and add the true root count when
+      // a cap was hit and it was computable — a floor can no longer be read as a
+      // total by a caller that only looks at the summary.
+      edgeLimit,
+      // The bound on the WHOLE answer, as distinct from the per-query site
+      // limit. Declared because the product of the per-query bound and the
+      // fan-out budget is otherwise unbounded, and unstated.
+      maxEdges,
+      totalEdgeLimitReached: totalLimitReached,
+      cappedQueries,
+      callersIfUncapped: totalCallersIfKnown,
+      calleesIfUncapped: totalCalleesIfKnown,
+      totalsAreLowerBounds,
+      // The owner cascade is a superset by design. These four numbers are how
+      // much of it is about the symbol that was actually asked for. An agent
+      // that sees `totalCallers: 184, exactCallers: 24` knows at once that the
+      // answer is mostly about the symbol's members — which no count above this
+      // line would ever have told it.
+      exactCallers,
+      cascadedCallers,
+      exactCallees,
+      cascadedCallees,
+      deeperCallers,
+      deeperCallees,
+      // The fan-out bound, and whether it bit. `truncationReason` can name
+      // `caller-budget-exhausted`; before this it did so without saying what
+      // the budget was, so the bound was announced and never quantified.
+      callerBudget,
+      calleeBudget,
+      callerBudgetExhausted,
+      calleeBudgetExhausted,
+      // What the answer is made of. With ten kinds in the default filter, a
+      // caller that wanted calls had no way to find out how many of the
+      // returned edges were calls without walking all of them.
+      edgesByType,
+      // The kinds this run actually searched, resolved — not a restatement of
+      // the default. The handler's scope echo carried its own hardcoded copy
+      // and went stale the moment the default was widened, so it named four
+      // kinds while the answer held `uses` and `contains` edges.
+      relationshipTypesUsed,
+      // Which kinds survive a bound first. Only observable under truncation,
+      // but published always: the cap's ORDER BY used to be indifferent to
+      // kind, so asking for MORE kinds returned FEWER call edges (measured on
+      // lodash: 99 calls alone, 71 inside the 230-edge default answer). The
+      // rule that decides that is now declared here.
+      edgeKindPriority,
+      // Rows present in BOTH callers and callees. `totalCallers + totalCallees`
+      // counts each of these twice, and the number above is the correction.
+      edgesInBothDirections,
+      // What the tool layer collapsed before handing edges
+      // to the agent. cascadeRepeatsCollapsed: the same stored row re-fetched
+      // by a deeper cascade. spellingVariantsCollapsed: same call site + same
+      // resolved target stored under different spellings, emitted once.
+      dedupedAtToolLayer
+    }
+  };
+}
+
+export {
+  STORED_LINE_SELECT,
+  storedLineFromRow,
+  ADDRESS_NOTES,
+  deriveCallSiteAddress,
+  addressLine0,
+  isExactAddress,
+  unattributedAddress,
+  traverseGraph,
+  resolveGraphRootDetailed,
+  likeContains,
+  resolveGraphRoot,
+  graphTraversal
+};