@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/chunk-BHB7BYYI.js

@@ -0,0 +1,626 @@
+import {
+  IDENTITY_TRAVERSABLE_TYPES,
+  memberFileMatches,
+  resolveMemberIdentity
+} from "./chunk-VL52PL2T.js";
+import {
+  classifyTier
+} from "./chunk-RCMTFSEF.js";
+import {
+  STORED_LINE_SELECT,
+  deriveCallSiteAddress,
+  graphTraversal,
+  storedLineFromRow,
+  unattributedAddress
+} from "./chunk-47HKX4AJ.js";
+import {
+  analysis_exclusions_exports
+} from "./chunk-SM7RFQRO.js";
+
+// src/lsp/impact.ts
+var IMPACT_BUDGET = {
+  /** maximum reverse-dependency nodes in one impact set */
+  maxNodes: 200,
+  /** traversal depth cap (mirrors the engine's own hard cap of 10) */
+  maxDepth: 5
+};
+var IMPACT_TRAVERSABLE_ROOT_TYPES = IDENTITY_TRAVERSABLE_TYPES;
+var IMPACT_REL_TYPES = ["calls", "instantiates", "extends", "implements"];
+var IMPACT_TOTAL_SCAN_CEILING = 5e4;
+var IMPACT_TOTAL_EXPANSION_CEILING = 2e3;
+var IMPACT_TOTAL_TIME_CEILING_MS = 4e3;
+var IMPACT_WALK_TIME_CEILING_MS = 1500;
+var IMPACT_CALL_DEADLINE_MS = 3e3;
+var IMPACT_COUNT_MIN_BUDGET_MS = 400;
+function cascadePrefix(symbolId) {
+  return symbolId.includes(":") ? symbolId.slice(0, symbolId.lastIndexOf(":") + 1) : "";
+}
+function countImpactDependents(db, projectId, rootSymbolId, options = {}) {
+  const maxDepth = options.maxDepth ?? IMPACT_BUDGET.maxDepth;
+  const scanCeiling = options.scanCeiling ?? IMPACT_TOTAL_SCAN_CEILING;
+  const expansionCeiling = options.expansionCeiling ?? IMPACT_TOTAL_EXPANSION_CEILING;
+  const timeCeilingMs = options.timeCeilingMs ?? IMPACT_TOTAL_TIME_CEILING_MS;
+  const startedAt = Date.now();
+  const relTypes = options.relationshipTypes ?? IMPACT_REL_TYPES;
+  if (relTypes.length === 0) {
+    return {
+      total: null,
+      direct: 0,
+      rowsScanned: 0,
+      expansions: 0,
+      hitScanCeiling: false,
+      timedOut: false,
+      failed: true,
+      skipped: false,
+      depths: /* @__PURE__ */ new Map(),
+      parents: /* @__PURE__ */ new Map(),
+      cascade: null
+    };
+  }
+  const relPlaceholders = relTypes.map(() => "?").join(",");
+  const BATCH = 200;
+  const flatLevelSql = (n) => "SELECT s.id AS id, s.name AS name, f.relative_path AS file, r.target_symbol_id AS targetId 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 WHERE r.project_id = ? AND r.relationship_type IN (" + relPlaceholders + ") AND r.target_symbol_id IN (" + new Array(n).fill("?").join(",") + ")";
+  const rangeMembersSql = "SELECT id FROM brain_symbol WHERE project_id = ? AND owner_symbol_id >= ? AND owner_symbol_id < ?";
+  const TARGET_CHUNK = 400;
+  try {
+    const found = /* @__PURE__ */ new Set();
+    const depths = /* @__PURE__ */ new Map();
+    const opened = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    const parents = /* @__PURE__ */ new Map();
+    let frontier = [{ id: rootSymbolId, depth: 0 }];
+    let direct = 0;
+    let rowsScanned = 0;
+    let expansions = 0;
+    let hitScanCeiling = false;
+    let timedOut = false;
+    while (frontier.length > 0 && !hitScanCeiling) {
+      const next = [];
+      for (let start = 0; start < frontier.length; start += BATCH) {
+        if (Date.now() - startedAt > timeCeilingMs) {
+          timedOut = true;
+          hitScanCeiling = true;
+          break;
+        }
+        const batch = frontier.slice(start, start + BATCH).filter((entry) => !visited.has(entry.id));
+        if (batch.length === 0) continue;
+        for (const entry of batch) {
+          if (expansions >= expansionCeiling) {
+            hitScanCeiling = true;
+            break;
+          }
+          visited.add(entry.id);
+          opened.add(entry.id);
+          expansions++;
+        }
+        if (hitScanCeiling) break;
+        const targetIds = /* @__PURE__ */ new Set();
+        for (const entry of batch) targetIds.add(entry.id);
+        const ranges = /* @__PURE__ */ new Map();
+        for (const entry of batch) {
+          const prefix = cascadePrefix(entry.id);
+          if (!ranges.has(prefix)) ranges.set(prefix, prefix);
+        }
+        for (const prefix of ranges.values()) {
+          if (Date.now() - startedAt > timeCeilingMs) {
+            timedOut = true;
+            hitScanCeiling = true;
+            break;
+          }
+          const members = db.prepare(rangeMembersSql).all(projectId, prefix, prefix + ";");
+          for (const member of members) targetIds.add(member.id);
+        }
+        if (hitScanCeiling) break;
+        const flatTargets = [...targetIds];
+        const levelDepth = frontier[0].depth;
+        for (let chunkStart = 0; chunkStart < flatTargets.length; chunkStart += TARGET_CHUNK) {
+          if (Date.now() - startedAt > timeCeilingMs) {
+            timedOut = true;
+            hitScanCeiling = true;
+            break;
+          }
+          const chunk = flatTargets.slice(chunkStart, chunkStart + TARGET_CHUNK);
+          if (chunk.length === 0) continue;
+          const rows = db.prepare(flatLevelSql(chunk.length)).all(projectId, ...relTypes, ...chunk);
+          rowsScanned += rows.length;
+          for (const row of rows) {
+            if (!row.name || analysis_exclusions_exports.isNoiseSymbolName(row.name)) continue;
+            if (row.file && analysis_exclusions_exports.isHardNoisePath(row.file)) continue;
+            if (row.id === rootSymbolId) continue;
+            if (found.has(row.id)) continue;
+            found.add(row.id);
+            depths.set(row.id, levelDepth);
+            parents.set(row.id, row.targetId);
+            if (levelDepth === 0) direct++;
+            if (levelDepth + 1 < maxDepth) next.push({ id: row.id, depth: levelDepth + 1 });
+          }
+          if (rowsScanned > scanCeiling) {
+            hitScanCeiling = true;
+            break;
+          }
+        }
+        if (hitScanCeiling) break;
+      }
+      frontier = next;
+    }
+    return {
+      total: hitScanCeiling ? null : found.size,
+      direct,
+      rowsScanned,
+      expansions,
+      hitScanCeiling,
+      timedOut,
+      failed: false,
+      skipped: false,
+      depths,
+      parents,
+      cascade: classifyCascade(db, projectId, [...found], opened)
+    };
+  } catch {
+    return {
+      total: null,
+      direct: 0,
+      rowsScanned: 0,
+      expansions: 0,
+      hitScanCeiling: false,
+      timedOut: false,
+      failed: true,
+      skipped: false,
+      depths: /* @__PURE__ */ new Map(),
+      parents: /* @__PURE__ */ new Map(),
+      cascade: null
+    };
+  }
+}
+function classifyCascade(db, projectId, targets, opened) {
+  if (targets.length === 0) return { exact: 0, member: 0, rangeFolded: 0 };
+  const ownerById = /* @__PURE__ */ new Map();
+  try {
+    for (let i = 0; i < targets.length; i += 400) {
+      const slice = targets.slice(i, i + 400);
+      for (const row of db.prepare("SELECT id AS id, owner_symbol_id AS owner FROM brain_symbol WHERE project_id = ? AND id IN (" + slice.map(() => "?").join(",") + ")").all(projectId, ...slice)) {
+        ownerById.set(row.id, row.owner ?? null);
+      }
+    }
+  } catch {
+    return null;
+  }
+  let exact = 0;
+  let member = 0;
+  let rangeFolded = 0;
+  for (const id of targets) {
+    if (opened.has(id)) {
+      exact++;
+      continue;
+    }
+    const owner = ownerById.get(id) ?? null;
+    if (owner !== null && opened.has(owner)) member++;
+    else rangeFolded++;
+  }
+  return { exact, member, rangeFolded };
+}
+async function computeImpact(db, projectId, symbolName, deps = {}, memberFile, options = {}) {
+  const traverse = deps.traverse ?? graphTraversal;
+  const relationshipTypes = options.relationshipTypes ?? IMPACT_REL_TYPES;
+  if (relationshipTypes.length === 0) {
+    throw new Error(
+      "bb/impact: relationshipTypes must name at least one relationship kind \u2014 an empty list matches nothing and would be silently re-read as the engine's default"
+    );
+  }
+  const callStartedAt = Date.now();
+  const walk = {
+    direction: "callers",
+    maxDepth: IMPACT_BUDGET.maxDepth,
+    relationshipTypes: [...relationshipTypes],
+    timeBudgetMs: IMPACT_WALK_TIME_CEILING_MS
+  };
+  let resolution = { through: "direct" };
+  let result;
+  try {
+    result = await traverse(projectId, symbolName, walk);
+  } catch (error) {
+    const owner = resolveMemberIdentity(db, projectId, symbolName, memberFile);
+    if (owner === null) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("not found")) {
+        throw new Error(`bb/impact: symbol '${symbolName}' not found \u2014 no impact set exists (declared error; run \`bb index\` or check the name)`);
+      }
+      throw error;
+    }
+    result = await traverse(projectId, owner.name, walk);
+    if (!result.root || !result.root.id) {
+      throw error;
+    }
+    resolution = { through: "owning-declaration", memberName: symbolName, ownerName: owner.name, ...memberFile ? { memberFile } : {} };
+  }
+  const rootType = result.root?.symbolType ?? "";
+  const rootedAtRequestedName = result.root?.name === symbolName;
+  const kindOutsideWhitelist = rootType.length > 0 && !IMPACT_TRAVERSABLE_ROOT_TYPES.includes(rootType);
+  const { candidates: nameCandidates, total: nameTotal } = listNameCandidates(db, projectId, symbolName);
+  const hintMatchesRoot = memberFile !== void 0 && typeof result.root?.file === "string" && memberFileMatches(memberFile, result.root.file);
+  const nameIsUnambiguous = nameTotal === 1 || (nameTotal === null || nameTotal > 1) && hintMatchesRoot;
+  const VALUE_LIKE_KINDS = ["enum_member", "constant"];
+  const exemptKind = kindOutsideWhitelist && rootedAtRequestedName && nameIsUnambiguous && VALUE_LIKE_KINDS.includes(rootType) ? rootType : null;
+  if (kindOutsideWhitelist && exemptKind === null) {
+    const owner = resolveMemberIdentity(db, projectId, symbolName, memberFile);
+    if (owner === null) {
+      const candidates = (nameTotal ?? 0) > 1 ? ` \u2014 ${nameTotal} stored symbols carry that name: ${nameCandidates.slice(0, 8).map((c) => `${c.file || "?"}:${c.line}`).slice(0, 8).join(", ")}${nameTotal !== null && nameTotal > 8 ? `, +${nameTotal - 8} more` : ""}; re-ask with the \`file\` option naming one of them` : "";
+      throw new Error(
+        `bb/impact: symbol '${symbolName}' is not a traversable root (${rootType}) \u2014 no impact set exists (declared error: the symbol was not found as a traversable root${memberFile ? "; the supplied file hint does not identify it \u2014 pass a project-relative path to its defining file" : "; run `bb index` or check the name"}${candidates})`
+      );
+    }
+    result = await traverse(projectId, owner.name, walk);
+    if (!result.root || !result.root.id) throw new Error(`bb/impact: symbol '${symbolName}' not found \u2014 no impact set exists (declared error)`);
+    resolution = { through: "owning-declaration", memberName: symbolName, ownerName: owner.name, ...memberFile ? { memberFile } : {} };
+  } else if (memberFile && result.root && rootType && IMPACT_TRAVERSABLE_ROOT_TYPES.includes(rootType)) {
+    if (typeof result.root.file !== "string" || !memberFileMatches(memberFile, result.root.file)) {
+      throw new Error(
+        `bb/impact: symbol '${symbolName}' resolves to '${result.root.file}' but the supplied file hint '${memberFile}' does not identify it \u2014 refusing to answer about a different copy (declared error; pass the symbol's own file, or omit \`file\` when the name is unique)`
+      );
+    }
+  }
+  if (!result.root || !result.root.id) {
+    throw new Error(`bb/impact: symbol '${symbolName}' not found \u2014 no impact set exists (declared error; run \`bb index\` or check the name)`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const impact = [];
+  let truncated = false;
+  let truncationReason = null;
+  const edges = [...result.callers].sort((a, b) => a.depth - b.depth);
+  for (const edge of edges) {
+    if (impact.length >= IMPACT_BUDGET.maxNodes) {
+      truncated = true;
+      truncationReason = "impact-node-budget-exhausted";
+      break;
+    }
+    const nodeId = edge.from;
+    if (nodeId === result.root.id) continue;
+    if (seen.has(nodeId)) continue;
+    seen.add(nodeId);
+    const node = result.nodes[nodeId];
+    impact.push({
+      id: nodeId,
+      name: node?.name ?? nodeId,
+      file: node?.file ?? "",
+      filePath: node?.filePath ?? "",
+      // The ENGINE's address for this edge, served whole. The engine
+      // derived it from the same stored row this entry quotes (provisional
+      // evidence at the engine's first-trace depth; the re-read below replaces
+      // it whenever the depth moves). A dependent's DECLARATION is not a
+      // position claim about the usage, so it goes in its own declared field.
+      callSite: edge.callSite,
+      rowId: edge.rowId,
+      declarationLine: node?.line ?? 0,
+      symbolType: node?.symbolType ?? "",
+      language: node?.language ?? "",
+      depth: edge.depth,
+      // Provisional, and rewritten below wherever `depth` moved: the evidence
+      // below belongs to the engine's row, and the engine's row may not be the
+      // one at the shortest path this entry reports.
+      evidenceAtDepth: edge.depth,
+      relationshipType: edge.relationshipType,
+      confidence: edge.confidence,
+      // The ONE server-side classifier. A second derivation
+      // here would be the exact defect that module was written to close.
+      tier: classifyTier({
+        relationshipType: edge.relationshipType,
+        confidence: edge.confidence,
+        evidenceClass: edge.metadata?.evidenceClass ?? null
+      }),
+      isCrossLanguage: edge.isCrossLanguage === true,
+      bridgeMechanism: edge.bridgeMechanism ?? null,
+      // The engine already classifies every caller row as `exact` or
+      // `owner-cascade` and names the member it matched (bb_graph publishes
+      // both). Reading them here is the point: a second derivation would be the
+      // defect that module exists to prevent, and a dropped field is the defect
+      // was filed for.
+      via: edge.targetMatch === "owner-cascade" ? "member" : "exact",
+      ...edge.matchedMember ? { viaMember: edge.matchedMember } : {},
+      // The walk node this row was found at, which is what the cascade
+      // classification below judges the named member against. It stays off the
+      // wire: it is an internal id the reader has no use for, and `via` is the
+      // reader-facing half of the same fact.
+      tracedId: edge.to
+    });
+  }
+  const memberOwner = /* @__PURE__ */ new Map();
+  let unresolvedMembers = 0;
+  for (const entry of impact) {
+    if (entry.via !== "member" || !entry.viaMember) continue;
+    const traced = entry.tracedId ?? "";
+    const key = `${entry.viaMember.name}\0${entry.viaMember.file}\0${traced}`;
+    if (!memberOwner.has(key)) {
+      const owner = memberOwnerOf(db, projectId, entry.viaMember, traced);
+      memberOwner.set(key, owner);
+      if (owner === "unknown") unresolvedMembers++;
+    }
+    if (memberOwner.get(key) === "range-folded") entry.via = "range-folded";
+  }
+  const reasons = [];
+  for (const reason of (result.summary?.truncationReason ?? "").split("+")) {
+    const clause = reason.trim();
+    if (clause.length === 0 || clause.startsWith("relationshipTypes:")) continue;
+    truncated = true;
+    if (!reasons.includes(clause)) reasons.push(clause);
+  }
+  const walkTimeBoundFired = reasons.some((clause) => clause === "walk-time-budget-exhausted");
+  truncationReason = truncationReason ?? (reasons.length > 0 ? `traversal: ${reasons.join("+")}` : null);
+  if (walkTimeBoundFired) {
+    truncationReason = truncationReason === null ? "walk: time-budget-exhausted" : `${truncationReason} (walk: time-budget-exhausted \u2014 this answer is not reproducible)`;
+  }
+  const directFromSet = impact.reduce((n, entry) => entry.depth === 0 ? n + 1 : n, 0);
+  const depthReached = impact.reduce((n, entry) => entry.depth > n ? entry.depth : n, 0);
+  const boundaryReached = depthReached >= IMPACT_BUDGET.maxDepth - 1;
+  const boundarySuspect = boundaryReached && boundaryHasDependents(db, projectId, impact, relationshipTypes);
+  const verify = truncated || boundarySuspect;
+  const callElapsedMs = Date.now() - callStartedAt;
+  const countBudgetMs = Math.max(0, Math.min(IMPACT_TOTAL_TIME_CEILING_MS, IMPACT_CALL_DEADLINE_MS - callElapsedMs));
+  const countSkipped = verify && countBudgetMs < IMPACT_COUNT_MIN_BUDGET_MS;
+  const counts = !verify ? {
+    total: impact.length,
+    direct: directFromSet,
+    hitScanCeiling: false,
+    timedOut: false,
+    failed: false,
+    skipped: false,
+    depths: /* @__PURE__ */ new Map(),
+    parents: /* @__PURE__ */ new Map(),
+    cascade: null
+  } : countSkipped ? {
+    total: null,
+    direct: 0,
+    rowsScanned: 0,
+    expansions: 0,
+    hitScanCeiling: false,
+    timedOut: false,
+    failed: false,
+    skipped: true,
+    depths: /* @__PURE__ */ new Map(),
+    parents: /* @__PURE__ */ new Map(),
+    cascade: null
+  } : countImpactDependents(db, projectId, result.root.id, { maxDepth: IMPACT_BUDGET.maxDepth, relationshipTypes, timeCeilingMs: countBudgetMs });
+  if (counts.depths.size > 0) {
+    for (const entry of impact) {
+      const measured = counts.depths.get(entry.id);
+      if (measured !== void 0 && measured !== entry.depth) entry.depth = measured;
+    }
+    impact.sort((a, b) => a.depth - b.depth || a.id.localeCompare(b.id));
+    const reread = /* @__PURE__ */ new Map();
+    for (const entry of impact) {
+      if (entry.evidenceAtDepth === entry.depth) continue;
+      const parent = counts.parents.get(entry.id);
+      if (parent === void 0) {
+        entry.relationshipType = null;
+        entry.tier = null;
+        entry.isCrossLanguage = null;
+        entry.bridgeMechanism = null;
+        entry.confidence = null;
+        entry.evidenceAtDepth = null;
+        entry.callSite = unattributedAddress(entry.file);
+        continue;
+      }
+      const key = `${entry.id} ${parent}`;
+      if (!reread.has(key)) reread.set(key, storedRowEvidence(db, projectId, entry.id, parent, relationshipTypes));
+      const row = reread.get(key);
+      if (!row) {
+        entry.relationshipType = null;
+        entry.tier = null;
+        entry.isCrossLanguage = null;
+        entry.bridgeMechanism = null;
+        entry.confidence = null;
+        entry.evidenceAtDepth = null;
+        entry.callSite = unattributedAddress(entry.file);
+        continue;
+      }
+      entry.relationshipType = row.relationshipType;
+      entry.confidence = row.confidence;
+      entry.isCrossLanguage = row.isCrossLanguage;
+      entry.bridgeMechanism = row.bridgeMechanism;
+      entry.callSite = row.callSite;
+      entry.tier = classifyTier({
+        relationshipType: row.relationshipType,
+        confidence: row.confidence,
+        evidenceClass: row.evidenceClass
+      });
+      entry.evidenceAtDepth = entry.depth;
+    }
+  }
+  const unmeasurable = counts.hitScanCeiling || counts.failed || counts.skipped;
+  const total = unmeasurable ? null : counts.total;
+  const direct = unmeasurable ? null : counts.direct;
+  const depthCapFired = reasons.includes("caller-depth-cap-reached");
+  const provenComplete = verify && !unmeasurable && counts.timedOut !== true && counts.total === impact.length && !depthCapFired;
+  if (verify && counts.failed) {
+    truncated = true;
+    const clause = "count: measurement unavailable \u2014 the completeness walk could not read the index";
+    truncationReason = truncationReason === null ? clause : `${truncationReason} (${clause})`;
+  } else if (verify && counts.hitScanCeiling) {
+    truncated = true;
+    truncationReason = truncationReason ?? "impact-completeness-unverifiable-at-depth-boundary";
+  } else if (verify && counts.skipped) {
+    truncated = true;
+    const clause = `count: skipped \u2014 the walk left less than ${IMPACT_COUNT_MIN_BUDGET_MS} ms of the ${IMPACT_CALL_DEADLINE_MS} ms call deadline; the total was not measured`;
+    truncationReason = truncationReason === null ? clause : `${truncationReason} (${clause})`;
+  } else if (verify && counts.total !== impact.length) {
+    truncated = true;
+    truncationReason = truncationReason ?? "impact-set-shorter-than-unbounded-walk";
+  }
+  if (provenComplete && !walkTimeBoundFired) {
+    truncated = false;
+    truncationReason = null;
+  }
+  if (verify && counts.timedOut === true) {
+    truncated = true;
+    const clause = "count: time-budget-exhausted \u2014 this answer is not reproducible";
+    truncationReason = truncationReason === null ? clause : `${truncationReason} (${clause})`;
+  }
+  if (countSkipped) {
+    const clause = "count: skipped for the call deadline \u2014 this answer is not reproducible";
+    truncationReason = truncationReason === null ? clause : `${truncationReason} (${clause})`;
+  }
+  const summary = result.summary;
+  let cascade = { exact: 0, member: 0, rangeFolded: 0 };
+  if (unresolvedMembers === 0) {
+    let exact = 0;
+    let member = 0;
+    let rangeFolded = 0;
+    for (const entry of impact) {
+      if (entry.via === "exact") exact++;
+      else if (entry.via === "member") member++;
+      else rangeFolded++;
+    }
+    cascade = { exact, member, rangeFolded };
+  } else {
+    cascade = null;
+  }
+  return {
+    root: {
+      id: result.root.id,
+      name: result.root.name,
+      file: result.root.file,
+      filePath: result.root.filePath ?? "",
+      line: result.root.line ?? 0,
+      symbolType: result.root.symbolType ?? "",
+      language: result.root.language ?? ""
+    },
+    impact,
+    shownCount: impact.length,
+    totalCountIfKnown: total,
+    directCount: direct,
+    budget: {
+      maxNodes: IMPACT_BUDGET.maxNodes,
+      maxDepth: IMPACT_BUDGET.maxDepth,
+      totalScanCeiling: IMPACT_TOTAL_SCAN_CEILING,
+      totalExpansionCeiling: IMPACT_TOTAL_EXPANSION_CEILING,
+      totalTimeCeilingMs: countSkipped ? 0 : countBudgetMs,
+      walkTimeCeilingMs: IMPACT_WALK_TIME_CEILING_MS,
+      callDeadlineMs: IMPACT_CALL_DEADLINE_MS
+    },
+    traversal: {
+      depthReached: impact.reduce((n, entry) => entry.depth > n ? entry.depth : n, 0),
+      engineTruncated: summary?.truncated === true,
+      engineTruncationReason: summary?.truncationReason ?? null,
+      edgeLimit: summary?.edgeLimit ?? null,
+      cappedQueries: summary?.cappedQueries ?? null,
+      callersIfUncapped: summary?.callersIfUncapped ?? null,
+      returnedCallers: summary?.totalCallers ?? null,
+      walkTimeBudgetMs: summary?.timeBudgetMs ?? null,
+      walkTimeExhausted: summary?.timeBudgetExhausted === true,
+      totalsAreLowerBounds: summary?.totalsAreLowerBounds === true,
+      dedupedAtToolLayer: summary?.dedupedAtToolLayer ?? null
+    },
+    truncated,
+    truncationReason,
+    resolution,
+    rootMatch: {
+      requested: symbolName,
+      via: resolution.through === "owning-declaration" ? "owning-declaration" : result.root.name === symbolName ? exemptKind === null ? "exact" : "exact-exempt-kind" : "fuzzy-containment",
+      // From the SAME rows the declared error lists, so the count a reader sees
+      // in the payload and the list they see in a refusal are one measurement.
+      nameMatches: nameTotal !== null ? nameTotal : countExactNameMatches(db, projectId, symbolName)
+    },
+    rule: {
+      relationshipTypes: [...relationshipTypes],
+      cascade: "owner-cascade: a relationship stored against a member of a class is attributed to the whole owner family. The RANGE that implements it widens to the member's whole container, so siblings are folded in too; `cascade.rangeFolded` counts how many rows that accounts for in this answer",
+      noisePolicy: "hard-noise symbol names and paths are excluded, as in every other analysis surface",
+      maxDepth: IMPACT_BUDGET.maxDepth
+    },
+    cascade,
+    countVerification: {
+      ran: verify && !counts.skipped,
+      skipped: verify && counts.skipped,
+      timedOut: verify && counts.timedOut === true,
+      boundarySuspect,
+      complete: verify && !counts.skipped ? provenComplete : null
+    },
+    reproducible: !walkTimeBoundFired && !(verify && counts.timedOut === true) && !countSkipped
+  };
+}
+function storedRowEvidence(db, projectId, dependentId, parentId, relTypes) {
+  try {
+    const row = db.prepare(
+      "SELECT r.relationship_type AS relType, r.confidence AS confidence, r.is_cross_language AS isCross, r.bridge_mechanism AS bridge, r.metadata AS meta, " + STORED_LINE_SELECT + ", COALESCE(f.relative_path, f.path, '') AS srcFile, s.line_start AS srcLine FROM brain_relationship r LEFT JOIN brain_symbol s ON s.id = r.source_symbol_id LEFT JOIN brain_file f ON f.id = s.file_id WHERE r.project_id = ? AND r.source_symbol_id = ? AND r.target_symbol_id = ? AND r.relationship_type IN (" + relTypes.map(() => "?").join(",") + ") LIMIT 1"
+    ).get(projectId, dependentId, parentId, ...relTypes);
+    if (!row) return null;
+    let evidenceClass = null;
+    if (row.meta) {
+      try {
+        const parsed = JSON.parse(row.meta);
+        if (typeof parsed.evidenceClass === "string") evidenceClass = parsed.evidenceClass;
+      } catch {
+        evidenceClass = null;
+      }
+    }
+    return {
+      relationshipType: row.relType,
+      confidence: typeof row.confidence === "number" ? row.confidence : 0,
+      isCrossLanguage: row.isCross === 1,
+      bridgeMechanism: row.bridge ?? null,
+      // The address OWNER decides what this row's stored line IS. This function
+      // never sees a raw number to publish: a legacy `0` and a NULL both leave
+      // here as declared states, and only a real positive line can be an exact
+      // call site.
+      callSite: deriveCallSiteAddress({
+        storedLine: storedLineFromRow(row),
+        file: row.srcFile,
+        callerDeclaration: { line: row.srcLine }
+      }),
+      evidenceClass
+    };
+  } catch {
+    return null;
+  }
+}
+function memberOwnerOf(db, projectId, member, tracedId) {
+  try {
+    const file = db.prepare("SELECT id AS id FROM brain_file WHERE project_id = ? AND (relative_path = ? OR path = ?) LIMIT 1").get(projectId, member.file, member.file);
+    if (!file) return "unknown";
+    const rows = db.prepare("SELECT id AS id, owner_symbol_id AS owner FROM brain_symbol WHERE project_id = ? AND file_id = ? AND name = ?").all(projectId, file.id, member.name);
+    if (rows.length === 0) return "unknown";
+    const prefix = cascadePrefix(tracedId);
+    let sawRangeOnly = false;
+    for (const row of rows) {
+      if (row.owner === null || tracedId.length === 0 || row.owner === tracedId) return "member";
+      if (prefix.length === 0 || row.owner < prefix || row.owner >= prefix + ";") return "member";
+      sawRangeOnly = true;
+    }
+    return sawRangeOnly ? "range-folded" : "member";
+  } catch {
+    return "unknown";
+  }
+}
+function boundaryHasDependents(db, projectId, impact, relationshipTypes) {
+  const lastDepth = Math.max(0, ...impact.map((entry) => entry.depth));
+  if (lastDepth === 0) return false;
+  const boundary = impact.filter((entry) => entry.depth === lastDepth).map((entry) => entry.id);
+  if (boundary.length === 0) return false;
+  const placeholders = relationshipTypes.map(() => "?").join(",");
+  const row = db.prepare(
+    "SELECT 1 AS any FROM brain_relationship r JOIN brain_symbol s ON s.id = r.source_symbol_id AND s.project_id = r.project_id WHERE r.project_id = ? AND r.relationship_type IN (" + placeholders + ") AND r.source_symbol_id IN (" + boundary.map(() => "?").join(",") + ") LIMIT 1"
+  ).get(projectId, ...relationshipTypes, ...boundary);
+  return row !== void 0;
+}
+function listNameCandidates(db, projectId, symbolName) {
+  try {
+    const total = db.prepare("SELECT COUNT(*) AS c FROM brain_symbol WHERE project_id = ? AND name = ?").get(projectId, symbolName);
+    const candidates = db.prepare(
+      "SELECT COALESCE(f.relative_path, f.path, '') AS file, s.line_start AS line FROM brain_symbol s LEFT JOIN brain_file f ON f.id = s.file_id WHERE s.project_id = ? AND s.name = ? ORDER BY COALESCE(f.relative_path, f.path, ''), s.line_start LIMIT 32"
+    ).all(projectId, symbolName).map((row) => ({ file: row.file, line: typeof row.line === "number" ? row.line : 0 }));
+    return { candidates, total: typeof total?.c === "number" ? total.c : null };
+  } catch {
+    return { candidates: [], total: null };
+  }
+}
+function countExactNameMatches(db, projectId, symbolName) {
+  try {
+    const row = db.prepare("SELECT COUNT(*) AS c FROM brain_symbol WHERE project_id = ? AND name = ?").get(projectId, symbolName);
+    return typeof row?.c === "number" && row.c > 0 ? row.c : 1;
+  } catch {
+    return 1;
+  }
+}
+
+export {
+  IMPACT_BUDGET,
+  computeImpact
+};