cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/mcp/local/local-backend.js

@@ -0,0 +1,4142 @@
+"use strict";
+/**
+ * Local Backend (Multi-Repo)
+ *
+ * Provides tool implementations using local .cgraphx/code/ indexes.
+ * Supports multiple indexed repositories via a global registry.
+ * LadybugDB connections are opened lazily per repo on first query.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalBackend = exports.REPO_ID_HASH_LENGTH = exports.IMPACT_RELATION_CONFIDENCE = exports.EPISTEMIC_CONSUMER_RELATION_TYPES = exports.EPISTEMIC_HERITAGE_RELATION_TYPES = exports.VALID_RELATION_TYPES = exports.VALID_NODE_LABELS = void 0;
+exports.isTestFilePath = isTestFilePath;
+exports.resolveWorktreeCwd = resolveWorktreeCwd;
+exports.buildDetectChangesDiffArgs = buildDetectChangesDiffArgs;
+exports.discoverGitSubprojects = discoverGitSubprojects;
+exports.attachToolStaleness = attachToolStaleness;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const pool_adapter_js_1 = require("../../core/lbug/pool-adapter.js");
+const bean_metadata_js_1 = require("./bean-metadata.js");
+const aop_metadata_js_1 = require("./aop-metadata.js");
+const query_params_js_1 = require("../../core/lbug/query-params.js");
+const line_display_js_1 = require("./line-display.js");
+const lbug_config_js_1 = require("../../core/lbug/lbug-config.js");
+const git_js_1 = require("../../storage/git.js");
+const fs_1 = require("fs");
+const repo_manager_js_1 = require("../../storage/repo-manager.js");
+const git_staleness_js_1 = require("../../core/git-staleness.js");
+const logger_js_1 = require("../../core/logger.js");
+const utils_js_1 = require("../../lib/utils.js");
+const unresolved_receivers_js_1 = require("../../core/ingestion/scope-resolution/unresolved-receivers.js");
+/**
+ * Candidate `type`s that label enrichment newly populates (#2687). Before that,
+ * these surfaced as `''`, which several resolution gates read as "kind unknown".
+ * Anything keyed on the empty string must name these explicitly.
+ */
+const VALUE_CANDIDATE_TYPES = new Set(['Const', 'Variable', 'Static']);
+/**
+ * Row cap on the name-resolution window in `resolveSymbolCandidates`. Named
+ * because the SQL `LIMIT` and the "is this window the complete match set?"
+ * guard must agree — a short page (`rows.length < CANDIDATE_WINDOW`) is the
+ * only truncation signal available when the COUNT leg fails.
+ */
+const CANDIDATE_WINDOW = 20;
+/**
+ * The pieces every ambiguous-resolution payload shares, derived once.
+ *
+ * `outcome.total` is the resolver's real match count, NOT `candidates.length` —
+ * the window caps at {@link CANDIDATE_WINDOW}, so reporting the array length
+ * claimed 20 matches when 92 existed. `totalIsLowerBound` must travel with that
+ * count everywhere it is
+ * reported (#2787 review F3), INCLUDING the prose, because the message is what
+ * an agent actually reads: without it a failed COUNT reads as an exact 20. And
+ * truncation is measured against `total`, never against the window — the old
+ * form said "6 of 20" when 92 matched.
+ *
+ * Six call sites rebuilt all of that by hand with slightly different spellings.
+ * Deriving it in one place is what stops the invariants drifting apart again.
+ *
+ * @param shownCount how many candidates the payload actually carries — the full
+ *   window for `context`/`trace`, the `AMBIGUOUS_MAX_CANDIDATES` slice for
+ *   `impact`.
+ * @param withTotal picks the suffix form: `(showing 6 of 92)` for the `impact`
+ *   paths that slice, `(showing 20)` for the paths that return the whole window.
+ */
+function ambiguityReport(outcome, shownCount, withTotal = false) {
+    const truncated = outcome.total > shownCount;
+    return {
+        atLeast: outcome.totalIsLowerBound ? 'at least ' : '',
+        showing: truncated
+            ? withTotal
+                ? ` (showing ${shownCount} of ${outcome.total})`
+                : ` (showing ${shownCount})`
+            : '',
+        fields: {
+            totalCandidates: outcome.total,
+            ...(outcome.totalIsLowerBound ? { totalIsLowerBound: true } : {}),
+            ...(truncated ? { candidatesTruncated: true } : {}),
+        },
+    };
+}
+/**
+ * Resolve a string tool param from its canonical name or legacy alias (#2175).
+ * Returns the first NON-BLANK string of [canonical, legacy] — the canonical (new)
+ * name is preferred when it carries a real value, otherwise the legacy value is used.
+ * A blank/whitespace new value therefore does NOT clobber a valid legacy value (e.g. a
+ * gradually-migrating client that always emits the new key, blank when unset). A
+ * non-string value (the MCP envelope is not schema-validated, so clients can send any
+ * JSON type) and an all-blank input resolve to `undefined`, so the caller returns a
+ * friendly required-param error instead of throwing `TypeError` on `.trim()`.
+ */
+function resolveAliasString(canonical, legacy) {
+    for (const value of [canonical, legacy]) {
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
+const TOOL_STRING_ALIASES = {
+    impact: [{ canonical: 'target', aliases: ['name', 'symbol'] }],
+    context: [{ canonical: 'file_path', aliases: ['file'] }],
+    trace: [{ canonical: 'from_file', aliases: ['file'] }],
+};
+/** callTool 分发的全部工具名（v1 工具集，恰好 9 个）。 */
+const KNOWN_TOOL_METHODS = new Set([
+    'context',
+    'impact',
+    'trace',
+    'cypher',
+    'detect_changes',
+    'route_map',
+    'api_impact',
+    'shape_check',
+    'tool_map',
+]);
+function normalizeToolParams(method, params) {
+    const input = params && typeof params === 'object' ? params : {};
+    const definitions = TOOL_STRING_ALIASES[method];
+    if (!definitions)
+        return { params: input };
+    const normalized = { ...input };
+    for (const { canonical, aliases } of definitions) {
+        const keys = [canonical, ...aliases];
+        const supplied = [];
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(input, key))
+                continue;
+            const value = input[key];
+            // Internal CLI callers materialize omitted optional flags as undefined.
+            if (value === undefined)
+                continue;
+            if (typeof value !== 'string' || !value.trim()) {
+                return { error: `Parameter ${method}.${key} must be a non-empty string.` };
+            }
+            supplied.push({ key, value: value.trim() });
+        }
+        const distinctValues = new Set(supplied.map(({ value }) => value));
+        if (distinctValues.size > 1) {
+            return {
+                error: `Conflicting parameters for ${method}.${canonical}: ${supplied
+                    .map(({ key }) => key)
+                    .join(', ')} must agree.`,
+            };
+        }
+        for (const alias of aliases)
+            delete normalized[alias];
+        if (supplied.length > 0)
+            normalized[canonical] = supplied[0].value;
+    }
+    if (method === 'impact' &&
+        typeof normalized.target !== 'string' &&
+        (typeof normalized.target_uid !== 'string' || !normalized.target_uid.trim())) {
+        return { error: 'impact requires target, name, symbol, or target_uid.' };
+    }
+    return { params: normalized };
+}
+/**
+ * Quick test-file detection for filtering impact results.
+ * Matches common test file patterns across all supported languages.
+ */
+function isTestFilePath(filePath) {
+    if (!filePath)
+        return false;
+    const p = filePath.toLowerCase().replace(/\\/g, '/');
+    return (p.includes('.test.') ||
+        p.includes('.spec.') ||
+        p.includes('__tests__/') ||
+        p.includes('__mocks__/') ||
+        p.includes('/test/') ||
+        p.includes('/tests/') ||
+        p.includes('/testing/') ||
+        p.includes('/fixtures/') ||
+        p.endsWith('_test.go') ||
+        p.endsWith('_test.py') ||
+        p.endsWith('_spec.rb') ||
+        p.endsWith('_test.rb') ||
+        p.includes('/spec/') ||
+        p.includes('/test_') ||
+        p.includes('/conftest.'));
+}
+/** Valid LadybugDB node labels for safe Cypher query construction */
+exports.VALID_NODE_LABELS = new Set([
+    'File',
+    'Folder',
+    'Function',
+    'Class',
+    'Interface',
+    'Method',
+    'CodeElement',
+    'Community',
+    'Process',
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+    'Route',
+    'Tool',
+]);
+/** Valid relation types for impact analysis filtering */
+exports.VALID_RELATION_TYPES = new Set([
+    'CALLS',
+    'IMPORTS',
+    'EXTENDS',
+    'IMPLEMENTS',
+    'HAS_METHOD',
+    'HAS_PROPERTY',
+    'METHOD_OVERRIDES',
+    'OVERRIDES', // Legacy alias — dual-read for pre-rename indexes
+    'METHOD_IMPLEMENTS',
+    'ACCESSES',
+    // 跨服务调用边:rpc-edges / http-api-calls 阶段产出(method→method 或
+    // method→ExternalService)。spec §4 要求 impact 默认遍历包含这两类边,
+    // 使"改一个服务的方法"能波及跨服务调用方——与 CALLS 同级,非 opt-in
+    // (区别于 INJECTS/WRAPS)。边自带 confidence(1.0 匹配 / 0.5 单侧孤儿)。
+    'RCALLS',
+    'HTTP_CALLS',
+    // Emitted by emit-references.ts / scope-resolution/graph-bridge/edges.ts and
+    // already part of the default impact relTypes + context() incoming queries.
+    // It was missing from this allowlist, so `impact({relationTypes:['USES']})`
+    // silently filtered to [] and fell back to the full default traversal
+    // (#2129/#1858 review F5). No IMPACT_RELATION_CONFIDENCE floor → 0.5 fallback,
+    // matching the FETCHES / WRAPS / HANDLES_ROUTE precedent below.
+    'USES',
+    'HANDLES_ROUTE',
+    'FETCHES',
+    'HANDLES_TOOL',
+    'ENTRY_POINT_OF',
+    'WRAPS',
+    // Emitted by the `di` pipeline phase (#2200 — DI collection injection,
+    // consumer Class → implementer Class). Valid here for explicit
+    // `relationTypes` filters, but deliberately NOT in the default impact()
+    // relTypes nor the context() incoming/outgoing lists — traversal is opt-in,
+    // like WRAPS/FETCHES. Also deliberately NO IMPACT_RELATION_CONFIDENCE entry
+    // (WRAPS/FETCHES precedent): the 0.5 unknown-type floor applies there,
+    // and the edges carry their own confidence (0.8) in the graph.
+    'INJECTS',
+    // Conditional and metadata-declaration evidence is opt-in for impact
+    // traversal, like INJECTS: explicit filters can follow activation
+    // constraints and declarations without changing the default callgraph
+    // surface.
+    'CONDITIONAL_ON',
+    'DECLARES',
+    // Spring proxy/advice evidence (#2416). Opt-in for traversal so existing
+    // impact defaults do not silently widen; target enrichment still surfaces
+    // advised/proxied state on ordinary impact calls.
+    'ADVISED_BY',
+]);
+/**
+ * Relation types the #1858 epistemic-boundary probe keys on. Kept as
+ * module-level `readonly` arrays (not Sets) because computeEpistemicBoundary
+ * binds them as Cypher query params (`r.type IN $heritage` / `IN $types`).
+ * The heritage set is exactly the IMPACT_RELATION_CONFIDENCE 0.85 tier —
+ * "statically verifiable, but the concrete binding past it is not".
+ */
+exports.EPISTEMIC_HERITAGE_RELATION_TYPES = [
+    'IMPLEMENTS',
+    'METHOD_IMPLEMENTS',
+    'EXTENDS',
+];
+exports.EPISTEMIC_CONSUMER_RELATION_TYPES = ['CALLS', 'USES', 'ACCESSES'];
+/**
+ * Per-relation-type confidence floor for impact analysis.
+ *
+ * When the graph stores a relation with a confidence value, that stored
+ * value is used as-is (it reflects resolution-tier accuracy from analysis
+ * time).  This map provides the floor for each edge type when no stored
+ * confidence is available, and is also used for display / tooltip hints.
+ *
+ * Rationale:
+ *   CALLS / IMPORTS  – direct, strongly-typed references → 0.9
+ *   EXTENDS          – class hierarchy, statically verifiable → 0.85
+ *   IMPLEMENTS       – interface contract, statically verifiable → 0.85
+ *   METHOD_OVERRIDES  – method override, statically verifiable → 0.85
+ *   METHOD_IMPLEMENTS – interface method implementation, statically verifiable → 0.85
+ *   HAS_METHOD       – structural containment → 0.95
+ *   HAS_PROPERTY     – structural containment → 0.95
+ *   ACCESSES         – field read/write, may be indirect → 0.8
+ *   CONTAINS         – folder/file containment → 0.95
+ *   RCALLS           – 跨服务 RPC 调用,serviceId+methodName 精确匹配 → 0.9(CALLS 同级)
+ *   HTTP_CALLS       – 跨服务 HTTP API 调用,URL+method 匹配 → 0.9(CALLS 同级)
+ *   (unknown type)   – conservative fallback → 0.5
+ */
+exports.IMPACT_RELATION_CONFIDENCE = {
+    CALLS: 0.9,
+    IMPORTS: 0.9,
+    EXTENDS: 0.85,
+    IMPLEMENTS: 0.85,
+    METHOD_OVERRIDES: 0.85,
+    METHOD_IMPLEMENTS: 0.85,
+    HAS_METHOD: 0.95,
+    HAS_PROPERTY: 0.95,
+    ACCESSES: 0.8,
+    CONTAINS: 0.95,
+    // 跨服务调用边(spec §4)。fork 未定义置信度,取 CALLS 同级 0.9。
+    // 这两类边在图中自带 confidence(1.0 匹配 / 0.5 单侧孤儿),优先用存储值;
+    // 此处 floor 仅在存储缺失时生效(显示/tooltip 兜底)。
+    RCALLS: 0.9,
+    HTTP_CALLS: 0.9,
+};
+/**
+ * Return the confidence floor for a given relation type.
+ * Falls back to 0.5 for unknown types so they are not silently elevated.
+ */
+const confidenceForRelType = (relType) => exports.IMPACT_RELATION_CONFIDENCE[relType ?? ''] ?? 0.5;
+/**
+ * Sort rank for the `confidence DESC` leg of {@link compareImpactEdgeStrength}.
+ * A null/non-numeric confidence ranks LAST (weakest), so a stored measurement
+ * always outranks a missing one. That is the same "keep the strongest evidence"
+ * intent the ordering exists for — and stating it here is the point: what an
+ * engine does with NULLs inside a DESC sort key is its choice, not ours.
+ */
+const impactEdgeConfidenceRank = (confidence) => typeof confidence === 'number' && Number.isFinite(confidence)
+    ? confidence
+    : Number.NEGATIVE_INFINITY;
+/**
+ * `relType ASC, confidence DESC, sourceId ASC` — decides which of several edges
+ * reaching the SAME node stamps its `relationType`/`confidence` onto that node's
+ * `impacted` entry. Total over those three columns, so the winner is a genuine
+ * argmax rather than "whichever row the engine happened to emit first".
+ */
+function compareImpactEdgeStrength(a, b) {
+    const byType = (0, utils_js_1.compareCodeUnits)(a.relType, b.relType);
+    if (byType !== 0)
+        return byType;
+    const aConfidence = impactEdgeConfidenceRank(a.confidence);
+    const bConfidence = impactEdgeConfidenceRank(b.confidence);
+    if (aConfidence !== bConfidence)
+        return aConfidence > bConfidence ? -1 : 1;
+    return (0, utils_js_1.compareCodeUnits)(a.sourceId, b.sourceId);
+}
+/**
+ * The whole former DB key: `id ASC` then {@link compareImpactEdgeStrength}.
+ * Orders the winning edges appended to `impacted` (distinct nodes, so `id` alone
+ * decides).
+ */
+function compareImpactFrontierEdges(a, b) {
+    return (0, utils_js_1.compareCodeUnits)(a.id, b.id) || compareImpactEdgeStrength(a, b);
+}
+/**
+ * Structured logging for *swallowed* query failures — replaces empty catch
+ * blocks. The level reflects telemetry severity, NOT a promise about the
+ * caller: most callers catch the failure and degrade to a genuinely safe
+ * fallback (a usable result, usually with a caller-visible `partial`/`ftsUsed`
+ * flag), so these are not operation-level errors and must not log at `error`:
+ *
+ *  - A benign missing optional table/label/column — a repo analyzed without
+ *    processes/communities, or a pre-v3 PDG index lacking the `calleeIds`
+ *    column — is a normal configuration, not a failure. Logged at `debug`
+ *    (suppressed at the default `info` level; surfaced only when troubleshooting).
+ *  - Any other swallowed failure is an unexpected-but-handled degradation:
+ *    logged at `warn` so it stays observable without raising a false `error`
+ *    alarm that would drown genuine, operation-aborting failures.
+ *
+ * `error` is intentionally NOT used here — it is reserved for failures that
+ * actually abort an operation, which log directly rather than through this
+ * best-effort-degradation helper.
+ *
+ * Contract for callers (#2283 review): only route a failure here when the
+ * caller ALSO surfaces the degradation in its result (a `partial` flag,
+ * `failed_files`, `traversalComplete:false`, …). A safety-critical path that
+ * would otherwise report success/clean (e.g. the `detect_changes` safety gate)
+ * MUST set that result-level signal — `warn` alone is not a substitute for an
+ * honest result.
+ */
+function logQueryError(context, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (isBenignMissingTableError(err)) {
+        logger_js_1.logger.debug({ context, err: msg }, 'GitNexus query skipped (missing optional data)');
+        return;
+    }
+    logger_js_1.logger.warn({ context, err: msg }, 'GitNexus query failed (degraded)');
+}
+/**
+ * A "missing table/label/relation" prepare error is benign for the query tool's
+ * best-effort enrichment: a repo analyzed without processes or communities simply
+ * has no `Process`/`Community` tables, so the `STEP_IN_PROCESS` / `MEMBER_OF`
+ * enrichment queries fail to prepare. That is a normal configuration, NOT a
+ * degraded result — it must not raise the `partial` flag (which callers would
+ * then learn to ignore). Real failures (timeouts, locks, native faults) do.
+ */
+function isBenignMissingTableError(err) {
+    const msg = err instanceof Error ? err.message : String(err ?? '');
+    // The `not (defined|found)` arm is scoped to a schema object (table/label/
+    // rel/column/property), mirroring lbug-adapter's isMissingColumnError
+    // (`/(table|column|property).*not found/i`): an unscoped "not found" matched
+    // operation failures like `rg: not found` (ripgrep absent) or `Symbol not
+    // found`, which this helper would then silently demote to `debug` (#2283).
+    return /does not exist|no such (table|label|rel)|unknown (table|label)|(table|label|rel|column|property)[^\n]*\bnot (defined|found)\b/i.test(msg);
+}
+const isReadOnlyDbError = (err) => {
+    // Walk the `cause` chain (bounded) so a wrapped read-only error (e.g. the
+    // pool adapter's `{ cause }` wrapper) is still detected here — this is the
+    // copy the MCP cypher handler uses to surface its curated read-only message
+    // (#2068 follow-up). Mirrors lbug-adapter's isReadOnlyDbError.
+    let cur = err;
+    for (let depth = 0; depth < 5 && cur != null; depth++) {
+        const msg = cur instanceof Error ? cur.message : String(cur);
+        if (/read-only database/i.test(msg))
+            return true;
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return false;
+};
+function epistemicFrom(dropped) {
+    // An index whose only drops were external still reports `exact` — nothing was
+    // lost — but carries the boundary count so "complete" is distinguishable from
+    // "we judged N calls to leave the program".
+    return dropped.notes.length === 0
+        ? dropped.external > 0
+            ? {
+                epistemic: 'exact',
+                causes: { receiverTyping: 0, dispatchBoundary: 0, externalBoundary: dropped.external },
+            }
+            : { epistemic: 'exact' }
+        : {
+            epistemic: 'lower-bound',
+            boundaries: [...dropped.notes],
+            // SITES, not notes. There is one note per symbol name but it reports N
+            // dropped sites, so counting notes would have published `1` next to
+            // prose saying `2 call sites` — a consumer branching on the number
+            // would read a different magnitude than the human reading the text.
+            causes: {
+                receiverTyping: dropped.sites,
+                dispatchBoundary: 0,
+                externalBoundary: dropped.external,
+            },
+        };
+}
+/** Resolve symlinks for path comparison; falls back to path.resolve on error.
+ * Uses `realpathSync.native` (not the pure-JS `realpathSync`) so that Windows
+ * 8.3 short names (e.g. RUNNER~1 → runneradmin) are expanded to long form,
+ * matching the output of `git rev-parse --show-toplevel`. */
+function tryRealpath(p) {
+    try {
+        return fs_1.realpathSync.native(p);
+    }
+    catch {
+        return path_1.default.resolve(p);
+    }
+}
+/**
+ * Resolve the git diff cwd for detect_changes, auto-detecting linked worktrees.
+ *
+ * When `launchCwd` is a linked worktree of the same canonical repository as
+ * `repoPath` (i.e. `getGitRoot(launchCwd)` differs from `repoPath` but both
+ * share the same `getCanonicalRepoRoot`), returns the worktree's git root so
+ * that `git diff` sees the correct working directory and index.
+ *
+ * Returns `repoPath` unchanged in all other cases (non-worktree, git
+ * unavailable, unrelated repo).
+ *
+ * Extracted as a module-level export so tests can pass any `launchCwd` instead
+ * of relying on `process.cwd()`, which is fixed to the server launch directory
+ * and cannot be changed mid-process.
+ */
+function resolveWorktreeCwd(repoPath, launchCwd) {
+    try {
+        // Verify repoPath is a git root before comparing against its canonical
+        // root. If getGitRoot returns a different path, repoPath is an arbitrary
+        // subdirectory — skip both the linked-worktree guard and auto-detection
+        // and fall through to the repoPath fallback.
+        const repoGitRoot = (0, git_js_1.getGitRoot)(repoPath);
+        const repoCanonical = repoGitRoot && tryRealpath(repoGitRoot) === tryRealpath(repoPath)
+            ? (0, git_js_1.getCanonicalRepoRoot)(repoPath)
+            : null;
+        // Early exit: if repoPath is a linked worktree (differs from its canonical
+        // main-checkout root), return it unchanged. Do NOT override it with the
+        // server's launch directory — that would silently replace the explicitly-
+        // resolved worktree index with the main checkout.
+        //
+        // getCanonicalRepoRoot returns the main-checkout path for both the checkout
+        // and all linked worktrees:
+        //   repoPath === canonical → main checkout (auto-detect may fire below)
+        //   repoPath !== canonical → linked worktree (return as-is)
+        if (repoCanonical && tryRealpath(repoPath) !== tryRealpath(repoCanonical)) {
+            return repoPath;
+        }
+        const launchGitRoot = (0, git_js_1.getGitRoot)(launchCwd);
+        if (launchGitRoot) {
+            // Normalise via realpathSync before comparing so macOS /var → /private/var
+            // symlinks (and Windows 8.3 short names) don't create false mismatches.
+            const realLaunch = tryRealpath(launchGitRoot);
+            const realRepo = tryRealpath(repoPath);
+            if (realLaunch !== realRepo) {
+                const launchCanonical = (0, git_js_1.getCanonicalRepoRoot)(launchCwd);
+                // Use tryRealpath on both canonical values for cross-platform safety.
+                if (launchCanonical &&
+                    repoCanonical &&
+                    tryRealpath(launchCanonical) === tryRealpath(repoCanonical)) {
+                    return launchGitRoot;
+                }
+            }
+        }
+    }
+    catch {
+        // Best-effort; fall through to repoPath.
+    }
+    return repoPath;
+}
+function buildDetectChangesDiffArgs(scope, baseRef) {
+    const args = ['diff', '--ignore-cr-at-eol'];
+    switch (scope) {
+        case 'staged':
+            return [...args, '--staged', '-U0'];
+        case 'all':
+            return [...args, 'HEAD', '-U0'];
+        case 'compare':
+            return baseRef ? [...args, baseRef, '-U0'] : null;
+        case 'unstaged':
+        default:
+            return [...args, '-U0'];
+    }
+}
+/**
+ * 在指定 cwd 运行一次 `git diff`(参数由 buildDetectChangesDiffArgs 构造)并解析为
+ * 逐文件 hunk。maxBuffer 256MB——Node 默认 1MB 在大未跟踪 diff 下会 ENOBUFS(见
+ * detectChanges 原始 bug "spawnSync git ENOBUFS")。失败时抛出含 git message 的
+ * Error,由调用方按单仓/子工程场景决定是整体失败还是记入 per-子工程说明。
+ *
+ * 动态 import('child_process') 与原 detectChanges 内联处一致——execFileSync 仅此
+ * 采集点使用,模块级缓存后无重复 spawn 开销。
+ */
+async function collectDetectChangesFileDiffs(diffCwd, diffArgs) {
+    const { execFileSync } = await import('child_process');
+    const output = execFileSync('git', diffArgs, {
+        cwd: diffCwd,
+        encoding: 'utf-8',
+        maxBuffer: 256 * 1024 * 1024,
+        windowsHide: true,
+    });
+    return (0, git_js_1.parseDiffHunks)(output);
+}
+/**
+ * 发现聚合根下的一级 git 子工程(spec §4 / T-13b)。
+ *
+ * 仅扫描 rootDir 的一级子目录,返回每个含 `.git` 条目(目录或 linked-worktree 的
+ * .git 文件)的子工程绝对路径,排序保证结果稳定(采集顺序确定)。用 hasGitDir 做
+ * 纯文件系统检查(不 spawn git),与 spec "一级子目录含 .git" 表述一致;隐藏目录
+ * (.cgraphx / .claude 等)跳过。
+ *
+ * 仅当 rootDir 自身非 git 仓库时由 detectChanges 调用——rootDir 是 git 仓库时走单仓
+ * 路径,不会进入此函数。导出以便测试直接覆盖发现逻辑。
+ */
+function discoverGitSubprojects(rootDir) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        // 仅一级子目录;隐藏目录(.cgraphx/.claude/.git 等)不是代码子工程。
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const child = path_1.default.join(rootDir, entry.name);
+        if ((0, git_js_1.hasGitDir)(child))
+            found.push(child);
+    }
+    return found.sort(utils_js_1.compareCodeUnits);
+}
+/**
+ * 逐子工程采集 git diff 并把 filePath 重写为相对聚合根(spec §4)。
+ *
+ * 索引里的 filePath 相对聚合根存储(filesystem-walker 以 repoPath 为基准,如
+ * `subA/src/foo.ts`),而 `git diff` 在子工程 subA 内输出相对 subA 的路径
+ * (`src/foo.ts`)。补 `<子工程相对根的目录>/<原路径>` 前缀后才能命中符号查询的
+ * `n.filePath ENDS WITH $filePath`,并使受影响符号自带子工程归属(可由路径推导)。
+ *
+ * 单个子工程失败(典型:compare 的 base-ref 在该子工程不存在)记入 errors 并继续,
+ * 不让一个子工程的缺 ref 拖垮整体;errors 随结果以 subproject_errors 带出。
+ * 顺序执行(v1 不并行优化,见任务注意事项)。
+ */
+async function collectSubprojectFileDiffs(aggregateRoot, subprojects, diffArgs) {
+    const fileDiffs = [];
+    const errors = [];
+    for (const sub of subprojects) {
+        try {
+            const diffs = await collectDetectChangesFileDiffs(sub, diffArgs);
+            const relPrefix = path_1.default.relative(aggregateRoot, sub).replace(/\\/g, '/');
+            for (const fd of diffs) {
+                fd.filePath = `${relPrefix}/${fd.filePath}`;
+            }
+            fileDiffs.push(...diffs);
+        }
+        catch (e) {
+            errors.push({
+                path: path_1.default.relative(aggregateRoot, sub).replace(/\\/g, '/'),
+                error: e?.message ?? String(e),
+            });
+        }
+    }
+    return { fileDiffs, errors };
+}
+/**
+ * Length of the path-derived suffix appended to a colliding repo id.
+ * Exported so tests can pin the suffix shape without re-deriving the
+ * literal; see `assignRepoId()` and the hashed-id resolution tier (#1658).
+ *
+ * Note: base64url is an *encoding*, not a hash — it preserves byte order, so
+ * two paths that share a long common prefix (sibling clones under one parent)
+ * collapse to the same sliced suffix. `assignRepoId()` keeps the legacy
+ * base64url suffix only for the first colliding duplicate (id compatibility)
+ * and falls back to a content hash of the resolved path on a real collision
+ * (#2054).
+ */
+exports.REPO_ID_HASH_LENGTH = 6;
+/**
+ * #2655: a tool result can carry a `staleness` field only if it is a plain
+ * object that isn't an error envelope and doesn't already carry one. Raw-array
+ * results (non-tabular `cypher` rows) are excluded because the CLI's `--limit`
+ * and other consumers branch on `Array.isArray`, so wrapping them would break
+ * that contract. Shared by `attachToolStaleness` and the dispatch site, which
+ * uses it to skip the freshness `git` spawn for results that can't carry it.
+ */
+function canCarryStaleness(result) {
+    return (result !== null &&
+        typeof result === 'object' &&
+        !Array.isArray(result) &&
+        !('error' in result) &&
+        !('staleness' in result));
+}
+/**
+ * #2655: attach a non-blocking `staleness` signal to a tool result when the
+ * index is behind HEAD, mirroring the `list_repos` `{commitsBehind, hint}`
+ * shape. Only ever ADDS a field to a carryable object result (see
+ * {@link canCarryStaleness}) — it never changes an existing result's shape.
+ */
+function attachToolStaleness(result, staleness) {
+    if (!staleness?.isStale || !canCarryStaleness(result)) {
+        return result;
+    }
+    return {
+        ...result,
+        staleness: { commitsBehind: staleness.commitsBehind, hint: staleness.hint },
+    };
+}
+class LocalBackend {
+    static TOOL_STALENESS_TTL_MS = 5000;
+    /**
+     * Explicit project root (`--path` / programmatic) that scopes cwd discovery
+     * (spec §8). When unset, discovery walks up from `process.cwd()`. Carried on
+     * the instance so every `refreshRepos()` re-read resolves the same root
+     * without callers threading it through each tool call.
+     */
+    explicitProjectRoot;
+    repos = new Map();
+    contextCache = new Map();
+    initializedRepos = new Set();
+    reinitPromises = new Map();
+    lastStalenessCheck = new Map();
+    // #2655: commit-behind freshness for the hot read tools. Stores the IN-FLIGHT
+    // promise (not just a timestamp) so N concurrent tool calls arriving before
+    // the first `git rev-list` resolves share one subprocess instead of each
+    // spawning their own; the resolved value is reused for TOOL_STALENESS_TTL_MS.
+    // Keyed by lbugPath (like lastStalenessCheck) — NOT repoPath — because flat
+    // and branch handles for one repo share a repoPath but carry different
+    // lastCommit values, so a repoPath key would serve one handle's freshness for
+    // the other; lbugPath is unique per flat/branch index.
+    toolStalenessCache = new Map();
+    // tri-review Residual-2: consolidates what were parallel per-poolKey Maps
+    // (lastObservedIndexedAt / lastObservedDbIdentity) touched in lockstep at
+    // every call site below — one Map, one delete, one shape. Keyed by lbugPath
+    // (not stored on the repo handle) because branch handles are produced fresh
+    // by applyBranchScope on every resolveRepo call, so mutating the handle would
+    // not persist across calls and the staleness check would reinit forever (#2106).
+    //   - `indexedAt`: last meta.indexedAt observed for an open pool.
+    //   - `dbIdentity`: file identity of the lbug the pool last opened (#2614 F1)
+    //     — an atomic swap or in-place incremental changes the inode; reiniting
+    //     on that covers the window where meta.indexedAt hasn't caught up (and
+    //     the incremental case), so a rebuilt index is never served stale even
+    //     when the stamp looks current.
+    lastObservedPoolState = new Map();
+    /** Merge-patch one poolKey's observed state, preserving fields not passed. */
+    setObservedState(poolKey, patch) {
+        const current = this.lastObservedPoolState.get(poolKey) ?? { dbIdentity: null };
+        this.lastObservedPoolState.set(poolKey, { ...current, ...patch });
+    }
+    /**
+     * One-shot stderr warnings for sibling-clone drift, keyed by
+     * `${repoId}|${cwdGitRoot}`. Without this guard every tool call
+     * from inside a sibling clone would print the same warning,
+     * making MCP stderr unreadable.
+     */
+    warnedSiblingDrift = new Set();
+    /**
+     * @param opts.projectRoot explicit project root overriding cwd discovery
+     *   (threaded from the CLI `--path` flag). Library consumers may omit it to
+     *   use the default cwd-based discovery.
+     */
+    constructor(opts) {
+        this.explicitProjectRoot = opts?.projectRoot;
+    }
+    /** Close all pooled LadybugDB connections (CLI one-shot; optional for long-lived MCP). */
+    async dispose() {
+        await (0, pool_adapter_js_1.closeLbug)();
+    }
+    // ─── Initialization ──────────────────────────────────────────────
+    /**
+     * Initialize from the discovered project root (cwd-based, or the explicit
+     * `--path` / `CGRAPH_REPO` override). Returns true if an index is available.
+     */
+    async init() {
+        await this.refreshRepos();
+        return this.repos.size > 0;
+    }
+    /**
+     * Re-discover the project-root index and update the in-memory repo map.
+     * With the global registry removed (spec §8), this resolves at most ONE repo
+     * via cwd discovery (or the explicit `--path` / `CGRAPH_REPO` override) and
+     * swaps it in atomically. LadybugDB connections for a previously-resolved
+     * repo that no longer resolves are pruned (they idle-timeout naturally).
+     */
+    async refreshRepos() {
+        const entries = await (0, repo_manager_js_1.listRegisteredRepos)({
+            validate: true,
+            explicitPath: this.explicitProjectRoot,
+        });
+        // Build the next map from scratch and swap it in atomically. Mutating the
+        // live map in place let stale entries influence fresh id assignment: a
+        // bare-name id, once handed to the first registry entry, stuck to it across
+        // refreshes and reorders, and colliding path suffixes silently overwrote
+        // each other so sibling clones disappeared from `list_repos` (#2054).
+        const nextRepos = new Map();
+        const nextContext = new Map();
+        const assigned = new Map(); // id -> resolved repo path
+        // Assign ids over a path-sorted view so a registered clone always gets the
+        // same id regardless of the registry's on-disk order: the bare name and
+        // each path-derived suffix become a pure function of the resolved-path set,
+        // not of iteration order, so a memorized id can't drift to a different
+        // clone after a registry reorder (#2067 follow-up).
+        const ordered = [...entries].sort((a, b) => {
+            const ra = path_1.default.resolve(a.path);
+            const rb = path_1.default.resolve(b.path);
+            return ra < rb ? -1 : ra > rb ? 1 : 0;
+        });
+        for (const entry of ordered) {
+            // path.resolve (not canonicalizePath) matches the pre-#2054 collision
+            // check and keeps refreshRepos free of mockable deps on the hot init
+            // path. registerRepo writes path.resolve'd paths (not realpath), and
+            // resolveRepoFromCache canonicalizes both sides when matching by path, so
+            // keying id assignment on path.resolve here is consistent and correct.
+            const resolved = path_1.default.resolve(entry.path);
+            const id = this.assignRepoId(entry.name, entry.path, resolved, assigned);
+            const storagePath = entry.storagePath;
+            const lbugPath = path_1.default.join(storagePath, 'lbug');
+            // Clean up any leftover KuzuDB files from before the LadybugDB migration.
+            // If kuzu exists but lbug doesn't, warn so the user knows to re-analyze.
+            const kuzu = await (0, repo_manager_js_1.cleanupOldKuzuFiles)(storagePath);
+            if (kuzu.found && kuzu.needsReindex) {
+                logger_js_1.logger.error(`GitNexus: "${entry.name}" has a stale KuzuDB index. Run: cgraph analyze ${entry.path}`);
+            }
+            const handle = {
+                id,
+                name: entry.name,
+                repoPath: entry.path,
+                storagePath,
+                lbugPath,
+                indexedAt: entry.indexedAt,
+                lastCommit: entry.lastCommit,
+                remoteUrl: entry.remoteUrl,
+                stats: entry.stats,
+                branch: entry.branch,
+                branches: entry.branches,
+            };
+            nextRepos.set(id, handle);
+            // Build lightweight context (no LadybugDB needed)
+            const s = entry.stats || {};
+            nextContext.set(id, {
+                projectName: entry.name,
+                stats: {
+                    fileCount: s.files || 0,
+                    functionCount: s.nodes || 0,
+                    communityCount: s.communities || 0,
+                    processCount: s.processes || 0,
+                },
+            });
+        }
+        // Prune per-clone pool state for databases that are no longer registered.
+        // The LadybugDB pool and the init/staleness/reinit maps are keyed by the
+        // immutable lbugPath (see ensureInitialized), so a repo id that merely
+        // moves to a different clone needs NO eviction — distinct clones have
+        // distinct lbugPaths and can never share a pool entry, which is what closes
+        // the resolve→query wrong-clone window for good (#2067). Only a path that
+        // dropped out of the registry must release its pooled connection + state.
+        const liveLbugPaths = new Set([...nextRepos.values()].map((h) => h.lbugPath));
+        // Branch pools (opened on demand by applyBranchScope) are NOT in this.repos
+        // — branch handles are minted fresh and discarded — so add every registered
+        // branch's lbugPath to the live set. Pure string work over the already-in-
+        // memory registry snapshot; no disk I/O on this hot path (#2106 R3).
+        for (const entry of entries) {
+            for (const b of entry.branches ?? []) {
+                liveLbugPaths.add((0, repo_manager_js_1.getStoragePaths)(entry.path, b.branch).lbugPath);
+            }
+        }
+        // initializedRepos is the authoritative set of OPENED pool keys (flat AND
+        // branch); union it with the previously-known flat handles so an orphaned
+        // branch pool (e.g. after `clean --branch` removes its summary) is closed
+        // and forgotten too, not just flat handles.
+        const knownKeys = new Set([
+            ...[...this.repos.values()].map((h) => h.lbugPath),
+            ...this.initializedRepos,
+        ]);
+        for (const key of knownKeys) {
+            if (liveLbugPaths.has(key))
+                continue;
+            this.initializedRepos.delete(key);
+            this.lastStalenessCheck.delete(key);
+            this.toolStalenessCache.delete(key);
+            this.lastObservedPoolState.delete(key);
+            this.reinitPromises.delete(key);
+            (0, pool_adapter_js_1.closeLbug)(key).catch(() => { });
+        }
+        this.repos = nextRepos;
+        this.contextCache = nextContext;
+    }
+    /**
+     * Assign a collision-free in-memory id for a registered repo.
+     *
+     * - Unique name → the bare lowercased name.
+     * - Duplicate name → a path-derived suffix. The *first* colliding clone keeps
+     *   the legacy `base64url(path)` suffix so ids generated before #2054 still
+     *   resolve (the #1658 hashed-id tier). base64url is an encoding, not a hash:
+     *   it preserves byte order, so sibling clones under one parent (e.g.
+     *   `.../REPO_2` and `.../REPO_3`) yield identical leading characters and thus
+     *   the same sliced suffix. Any further collision therefore falls back to a
+     *   content hash of the *resolved* path (order-insensitive), extended
+     *   deterministically until unique.
+     *
+     * `assigned` maps every id handed out in this refresh to its resolved path,
+     * so a candidate is "free" when it is unused or already owned by this exact
+     * path. This method records its own assignment into `assigned` before
+     * returning, so the map-update is the function's invariant, not a caller
+     * obligation. A returned id never overwrites a different path's handle (#2054).
+     */
+    assignRepoId(name, repoPath, resolved, assigned) {
+        const base = name.toLowerCase();
+        const free = (id) => {
+            const owner = assigned.get(id);
+            return owner === undefined || owner === resolved;
+        };
+        // Record the assignment so subsequent entries in the same refresh see this
+        // id as taken (the function owns its own invariant).
+        const claim = (id) => {
+            assigned.set(id, resolved);
+            return id;
+        };
+        if (free(base))
+            return claim(base);
+        // Legacy suffix from the *raw* path — kept byte-for-byte so the first
+        // colliding duplicate keeps the id it had before #2054 (#1658 tier).
+        const legacy = `${base}-${Buffer.from(repoPath)
+            .toString('base64url')
+            .slice(0, exports.REPO_ID_HASH_LENGTH)
+            .toLowerCase()}`;
+        if (free(legacy))
+            return claim(legacy);
+        // Real collision — hash the resolved path. Lowercase hex survives the
+        // `paramLower` lookup in resolveRepoFromCache.
+        const digest = (0, crypto_1.createHash)('sha256').update(resolved).digest('hex');
+        for (let len = exports.REPO_ID_HASH_LENGTH; len <= digest.length; len++) {
+            const candidate = `${base}-${digest.slice(0, len)}`;
+            if (free(candidate))
+                return claim(candidate);
+        }
+        // Two distinct resolved paths sharing a full SHA-256 digest is a hash
+        // break, not a runtime condition — fail loudly rather than silently
+        // overwrite a different repo's handle (#2054 invariant).
+        throw new Error(`GitNexus internal: unable to assign a unique repo id for "${name}" at ${repoPath}`);
+    }
+    // ─── Repo Resolution ─────────────────────────────────────────────
+    /**
+     * Resolve which repo to use.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If 0 or multiple without param, throw with helpful message
+     *
+     * On a miss, re-reads the registry once in case a new repo was indexed
+     * while the MCP server was running.
+     */
+    async resolveRepo(repoParam, branch) {
+        let refreshedAfterAmbiguity = false;
+        let result;
+        try {
+            result = this.resolveRepoFromCache(repoParam);
+        }
+        catch (err) {
+            if (!(err instanceof repo_manager_js_1.RegistryAmbiguousTargetError))
+                throw err;
+            // Stale in-memory duplicate siblings can linger after unregister; refresh
+            // once before re-throwing so a resolved registry can disambiguate (#1658).
+            await this.refreshRepos();
+            refreshedAfterAmbiguity = true;
+            result = this.resolveRepoFromCache(repoParam);
+        }
+        if (result) {
+            // Issue: silent graph drift across sibling clones.
+            // If the caller's cwd lives in a *different* on-disk clone of
+            // the same repo (matched by `remoteUrl`), warn once per
+            // (repo, cwd) pair on stderr. We do not fail or refuse to
+            // serve — the index is still the best answer we have — but
+            // the operator/agent has to know the answer may be stale.
+            this.maybeWarnSiblingDrift(result).catch(() => {
+                /* best-effort; never throw from resolveRepo */
+            });
+            return this.applyBranchScope(result, branch);
+        }
+        // Miss — refresh registry and try once more (skip if already refreshed above)
+        if (!refreshedAfterAmbiguity) {
+            await this.refreshRepos();
+        }
+        const retried = this.resolveRepoFromCache(repoParam);
+        if (retried) {
+            this.maybeWarnSiblingDrift(retried).catch(() => { });
+            return this.applyBranchScope(retried, branch);
+        }
+        // Still no match — throw with helpful message
+        if (this.repos.size === 0) {
+            throw new Error('No indexed repositories. Run: cgraph analyze');
+        }
+        // Build a disambiguated "Available: …" list (#829). When two handles
+        // share a name, annotate each colliding label with its path so the
+        // caller can actually pick the right one. Single-name entries render
+        // identically to pre-#829 output.
+        const nameCounts = new Map();
+        for (const h of this.repos.values()) {
+            const key = h.name.toLowerCase();
+            nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+        }
+        const labels = [...this.repos.values()].map((h) => (nameCounts.get(h.name.toLowerCase()) ?? 0) > 1 ? `${h.name} (${h.repoPath})` : h.name);
+        if (repoParam) {
+            throw new Error(`Repository "${repoParam}" not found. Available: ${labels.join(', ')}`);
+        }
+        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${labels.join(', ')}`);
+    }
+    /**
+     * Re-point a resolved repo handle at a specific branch index (#2106).
+     *
+     * - No `branch` (default) → the flat workspace handle, unchanged (backward
+     *   compatible: every existing caller passes no branch).
+     * - `branch` equal to the flat slot's **on-disk** recorded branch → the
+     *   flat handle. The disk meta is read before any cached state is trusted
+     *   (#2364 review F1): the flat slot follows the checked-out working tree
+     *   (#2354), so a plain analyze after a branch switch restamps the meta
+     *   without any repo-resolution miss that would refresh a long-lived
+     *   server's cached handle — the cached label can otherwise serve another
+     *   branch's content under the old name (the pool staleness reinit
+     *   hot-swaps content without updating `handle.branch`).
+     * - `branch` matching an indexed pinned branch → a handle whose
+     *   `lbugPath` points at `branches/<slug>/lbug`; the connection pool keys by
+     *   `lbugPath`, so this is the only change needed to scope every tool. The
+     *   sub-index lbug must actually exist on disk — `adoptFlatBranchLabel`
+     *   deletes the whole dir when the flat slot takes ownership, and a stale
+     *   cached summary must not route to the deleted path.
+     * - Cached `handle.branch` is trusted only when there is no readable flat
+     *   meta to contradict it (legacy shapes, #2106 R4).
+     * - Any miss → a clear error (never a silently-empty result against the
+     *   wrong DB), after exactly one `refreshRepos()` so newly-pinned branches
+     *   and restamped labels the cached handle predates resolve on the next
+     *   call.
+     */
+    async applyBranchScope(handle, branch) {
+        if (!branch)
+            return handle;
+        // At most one cache refresh per resolution: enough for the NEXT call to
+        // see fresh handles, without paying two registry re-scans when several
+        // stale arms fire in one degraded resolution.
+        let refreshed = false;
+        const refreshOnce = async () => {
+            if (refreshed)
+                return;
+            refreshed = true;
+            await this.refreshRepos().catch(() => { });
+        };
+        // One small JSON read per scoped call; mid-run meta writes preserve the
+        // old label until the end-of-run atomic stamp (run-analyze dirty stamps
+        // spread the existing meta), so this read never runs ahead of the DB.
+        const flatMeta = await (0, repo_manager_js_1.loadMeta)(path_1.default.dirname(handle.lbugPath));
+        if (flatMeta?.branch && flatMeta.branch === branch) {
+            // The disk meta decides routing, so it also supplies the metadata —
+            // the cached handle's label/commit/stats can predate the restamp.
+            return {
+                ...handle,
+                branch: flatMeta.branch,
+                indexedAt: flatMeta.indexedAt ?? handle.indexedAt,
+                lastCommit: flatMeta.lastCommit ?? handle.lastCommit,
+                stats: flatMeta.stats ?? handle.stats,
+            };
+        }
+        // A registry entry claiming `branch` both as the flat label AND as a
+        // pinned summary is an adopt-degraded state (rm kept the summary while
+        // the label restamped) — never serve the possibly stale-vintage pin for
+        // a label the flat slot claims; fall through to the honest error.
+        const summary = handle.branch !== branch ? handle.branches?.find((b) => b.branch === branch) : undefined;
+        if (summary) {
+            const { lbugPath } = (0, repo_manager_js_1.getStoragePaths)(handle.repoPath, branch);
+            // The lbug is the artifact the pool opens, so its presence is the
+            // serviceability truth — a half-deleted dir can outlive its meta.json
+            // while the lbug is gone, and vice versa (#2364 review F1 arm ii).
+            // Only provably-absent errno counts as missing: a transient EACCES/EIO
+            // on a healthy pinned sub-index must serve the handle (the pool open
+            // surfaces the real error) rather than a false "not indexed".
+            const probeCode = await promises_1.default.access(lbugPath).then(() => null, (e) => e?.code ?? 'UNKNOWN');
+            const subIndexMissing = probeCode === 'ENOENT' || probeCode === 'ENOTDIR';
+            if (!subIndexMissing) {
+                return {
+                    ...handle,
+                    lbugPath,
+                    indexedAt: summary.indexedAt,
+                    lastCommit: summary.lastCommit,
+                    stats: summary.stats,
+                };
+            }
+            // Stale summary (sub-index adopted/deleted): refresh so later calls see
+            // fresh handles, then fall through — the flat meta above is the truth.
+            await refreshOnce();
+        }
+        if (handle.branch && handle.branch === branch) {
+            // No readable flat meta (missing/corrupt — loadMeta → null): keep the
+            // pre-#2354 trust in the cached label (#2106 R4 legacy shapes). A
+            // readable meta that names another branch means the label is stale.
+            if (!flatMeta?.branch)
+                return handle;
+        }
+        // Every miss refreshes once before erroring: newly-pinned branches and
+        // restamped labels the cached handle predates become resolvable on the
+        // caller's next attempt (the cache otherwise only refreshes on repo-
+        // resolution misses and list_repos).
+        await refreshOnce();
+        // The flat slot's label comes from the authoritative meta when readable —
+        // never echo a cached label the meta just contradicted (a "not indexed:
+        // main / indexed: main" self-contradiction). Cached summaries may still
+        // lag; they are a hint, not a promise.
+        const flatLabel = flatMeta?.branch ?? handle.branch;
+        const indexed = [flatLabel, ...(handle.branches?.map((b) => b.branch) ?? [])].filter((b) => Boolean(b) && b !== branch);
+        const available = indexed.length > 0 ? indexed.join(', ') : '(workspace only)';
+        // Post-#2354 a bare `analyze --branch <X>` refuses to run unless X is
+        // checked out, so the guidance must lead with the checkout (#2364 F6).
+        throw new Error(`Branch "${branch}" is not indexed for "${handle.name}". ` +
+            `Indexed branches: ${available}. The workspace index follows the ` +
+            `checked-out branch — check out "${branch}" and re-run: cgraph analyze ` +
+            `(add --branch ${branch} while it is checked out to pin a separate sub-index).`);
+    }
+    /**
+     * Try to resolve a repo from the in-memory cache. Returns null on miss.
+     * Throws {@link RegistryAmbiguousTargetError} when `repoParam` matches
+     * multiple handles by name and cwd cannot disambiguate (#1658).
+     */
+    resolveRepoFromCache(repoParam) {
+        if (this.repos.size === 0)
+            return null;
+        if (repoParam) {
+            const paramLower = repoParam.toLowerCase();
+            const looksLikePath = path_1.default.isAbsolute(repoParam) || repoParam.includes(path_1.default.sep) || repoParam.includes('/');
+            const resolvePathMatch = () => {
+                const canonicalTarget = (0, repo_manager_js_1.canonicalizePath)(repoParam);
+                return [...this.repos.values()].find((handle) => {
+                    const stored = (0, repo_manager_js_1.canonicalizePath)(handle.repoPath);
+                    return process.platform === 'win32'
+                        ? stored.toLowerCase() === canonicalTarget.toLowerCase()
+                        : stored === canonicalTarget;
+                });
+            };
+            // Path-like params first (absolute or contains separators) — aligns with
+            // resolveRegistryEntry (#829). Bare aliases such as ".tmp-repro-mini" must
+            // not be resolved via path.resolve(cwd) before duplicate-name handling.
+            if (looksLikePath) {
+                const pathMatch = resolvePathMatch();
+                if (pathMatch)
+                    return pathMatch;
+            }
+            // Exact name before id — the first duplicate sibling keeps id === name
+            // (e.g. id "shared"), so a name lookup must not be captured by the id tier.
+            const nameMatches = [...this.repos.values()].filter((handle) => handle.name.toLowerCase() === paramLower);
+            if (nameMatches.length === 1)
+                return nameMatches[0];
+            if (nameMatches.length > 1) {
+                const cwdPick = this.pickRepoHandleForCwd(nameMatches);
+                if (cwdPick)
+                    return cwdPick;
+                throw new repo_manager_js_1.RegistryAmbiguousTargetError(repoParam, nameMatches.map((h) => this.handleToRegistryEntry(h)));
+            }
+            // Stable hashed id (e.g. "shared-abc123") from repoId() collision suffix
+            if (this.repos.has(paramLower))
+                return this.repos.get(paramLower);
+            // Bare name resolved as a cwd-relative path (e.g. "myrepo" against process.cwd()),
+            // after name/id tiers. Path-like strings with separators were handled at the top.
+            if (!looksLikePath) {
+                const pathMatch = resolvePathMatch();
+                if (pathMatch)
+                    return pathMatch;
+            }
+            // Partial name — only when unambiguous
+            const partialMatches = [...this.repos.values()].filter((handle) => handle.name.toLowerCase().includes(paramLower));
+            if (partialMatches.length === 1)
+                return partialMatches[0];
+            return null;
+        }
+        if (this.repos.size === 1) {
+            return this.repos.values().next().value;
+        }
+        return null; // Multiple repos, no param — ambiguous
+    }
+    /**
+     * Prefer the indexed repo whose path matches the git root of process.cwd().
+     *
+     * In MCP stdio server mode, `process.cwd()` is the server's launch directory,
+     * not the agent client's cwd. If the server was started from an unrelated
+     * directory, `getGitRoot` returns null and duplicate-name resolution throws
+     * {@link RegistryAmbiguousTargetError} — callers should pass an absolute path.
+     */
+    pickRepoHandleForCwd(candidates) {
+        const cwdRoot = (0, git_js_1.getGitRoot)(process.cwd());
+        if (!cwdRoot)
+            return null;
+        const canonicalCwd = (0, repo_manager_js_1.canonicalizePath)(cwdRoot);
+        const cwdMatches = candidates.filter((handle) => {
+            const stored = (0, repo_manager_js_1.canonicalizePath)(handle.repoPath);
+            return process.platform === 'win32'
+                ? stored.toLowerCase() === canonicalCwd.toLowerCase()
+                : stored === canonicalCwd;
+        });
+        return cwdMatches.length === 1 ? cwdMatches[0] : null;
+    }
+    handleToRegistryEntry(handle) {
+        return {
+            name: handle.name,
+            path: handle.repoPath,
+            storagePath: handle.storagePath,
+            indexedAt: handle.indexedAt,
+            lastCommit: handle.lastCommit,
+            stats: handle.stats,
+            remoteUrl: handle.remoteUrl,
+        };
+    }
+    // ─── Lazy LadybugDB Init ────────────────────────────────────────────
+    /**
+     * Ensure the LadybugDB pool is open for the *resolved* repo.
+     *
+     * Takes the `RepoHandle` the caller resolved — NOT a bare id — and keys the
+     * pool (and the init/staleness/reinit maps) by the immutable `lbugPath`. Two
+     * things matter for multi-clone correctness: (1) the handle is the one the
+     * caller resolved, so a concurrent `refreshRepos` can't substitute a different
+     * clone; (2) the pool key is the database path, so distinct clones never share
+     * a pool entry even when their name-derived id transiently collides (#2067).
+     */
+    async ensureInitialized(repo) {
+        const poolKey = repo.lbugPath;
+        // If a reinit is already in progress for this repo, wait for it
+        const pending = this.reinitPromises.get(poolKey);
+        if (pending)
+            return pending;
+        // Check if the index was rebuilt since we opened the connection (#297).
+        // Throttle staleness checks to at most once per 5 seconds per repo to
+        // avoid an fs.readFile round-trip on every tool invocation.
+        if (this.initializedRepos.has(poolKey) && (0, pool_adapter_js_1.isLbugReady)(poolKey)) {
+            const now = Date.now();
+            const lastCheck = this.lastStalenessCheck.get(poolKey) ?? 0;
+            if (now - lastCheck < 5000)
+                return; // Checked recently — skip
+            this.lastStalenessCheck.set(poolKey, now);
+            try {
+                // Read the metadata that sits next to THIS handle's lbug. For the
+                // flat/primary handle this is `<storagePath>/cgraph.json`; for a
+                // branch handle it is `<storagePath>/branches/<slug>/cgraph.json`.
+                // loadMeta falls back to legacy meta.json during migration.
+                // Reading the flat meta for a branch handle would compare the branch
+                // index's indexedAt against the primary's and thrash the pool (#2106).
+                const meta = await (0, repo_manager_js_1.loadMeta)(path_1.default.dirname(repo.lbugPath));
+                const observedState = this.lastObservedPoolState.get(poolKey);
+                // Compare against the last indexedAt OBSERVED for this pool (keyed by
+                // lbugPath), not the handle's — branch handles are fresh spreads so a
+                // handle mutation would not persist and would reinit on every check.
+                const observed = observedState?.indexedAt ?? repo.indexedAt;
+                const stampChanged = !!meta?.indexedAt && meta.indexedAt !== observed;
+                // #2614 F1: also reinit on a file-identity change. An atomic swap (or an
+                // in-place incremental) changes the lbug inode; keying only on
+                // meta.indexedAt let a reader that reinited inside the pre-swap window
+                // latch on the old inode forever (its stamp already == meta.indexedAt).
+                const currentIdentity = await (0, pool_adapter_js_1.statDbIdentity)(repo.lbugPath);
+                const identityChanged = (0, pool_adapter_js_1.dbIdentityChanged)(observedState?.dbIdentity ?? null, currentIdentity);
+                if (stampChanged || identityChanged) {
+                    // Index was rebuilt/swapped — DELEGATE the close/reopen to the pool's
+                    // initLbug, which refuses to evict (and close the shared Database)
+                    // while a query is in flight (its checkedOut>0 guard). Calling
+                    // closeLbug directly here bypassed that guard and could close a
+                    // Database mid-query — a native use-after-free (#2614). Wrap in
+                    // reinitPromises to serialize concurrent detectors.
+                    const reinit = (async () => {
+                        try {
+                            const reopened = await (0, pool_adapter_js_1.initLbug)(poolKey, repo.lbugPath);
+                            // tri-review NEW-7: advance the observed stamp watermark only
+                            // AFTER initLbug completes, not before calling it — still
+                            // regardless of `reopened` true/false (a stamp change with an
+                            // unchanged file must not re-trigger on every check), but if
+                            // initLbug THROWS the watermark must stay at its old value so
+                            // the next staleness check retries, instead of a failed reinit
+                            // silently latching as "already applied" and never trying again.
+                            const patch = {};
+                            if (meta?.indexedAt)
+                                patch.indexedAt = meta.indexedAt;
+                            // Advance the observed IDENTITY only when the pool actually rolled
+                            // over. If a query was in flight, initLbug served the current
+                            // handle and returned false; leaving the identity divergent
+                            // re-triggers the reopen on a later idle check instead of latching.
+                            if (reopened)
+                                patch.dbIdentity = await (0, pool_adapter_js_1.statDbIdentity)(repo.lbugPath);
+                            this.setObservedState(poolKey, patch);
+                        }
+                        finally {
+                            this.reinitPromises.delete(poolKey);
+                        }
+                    })();
+                    this.reinitPromises.set(poolKey, reinit);
+                    return reinit;
+                }
+                else {
+                    return; // Pool is current
+                }
+            }
+            catch {
+                return; // Can't read meta — assume pool is fine
+            }
+        }
+        try {
+            await (0, pool_adapter_js_1.initLbug)(poolKey, repo.lbugPath);
+            this.initializedRepos.add(poolKey);
+            this.setObservedState(poolKey, {
+                indexedAt: repo.indexedAt,
+                dbIdentity: await (0, pool_adapter_js_1.statDbIdentity)(repo.lbugPath),
+            });
+        }
+        catch (err) {
+            // If lock error, mark as not initialized so next call retries
+            this.initializedRepos.delete(poolKey);
+            throw err;
+        }
+    }
+    // ─── Public Getters ──────────────────────────────────────────────
+    /**
+     * Get context for a specific repo (or the single repo if only one).
+     */
+    getContext(repoId) {
+        if (repoId && this.contextCache.has(repoId)) {
+            return this.contextCache.get(repoId);
+        }
+        if (this.repos.size === 1) {
+            return this.contextCache.values().next().value ?? null;
+        }
+        return null;
+    }
+    /**
+     * Best-effort sibling-clone drift warning.
+     *
+     * When the resolved index has a `remoteUrl` recorded and the caller's
+     * `process.cwd()` is inside a *different* clone of the same repo, emit
+     * one stderr line per (repo, cwd) pair so the operator knows the
+     * graph may be stale relative to what's actually on disk under their
+     * cwd. Silent on path matches and on repos without a remote URL.
+     *
+     * Limitation: in MCP stdio server mode `process.cwd()` is the
+     * server's CWD at start time, *not* the agent client's CWD. The
+     * warning therefore only fires when the MCP server itself was
+     * launched from inside a sibling clone (typical for `npx cgraph
+     * serve` from a polecat workspace). Surfacing the client's CWD
+     * would require a per-tool-call `cwd` parameter — out of scope for
+     * the current MCP contract.
+     *
+     * Pure side-effect (stderr); never affects the returned handle.
+     * After the first computation for a given (repo, cwd) pair the
+     * result is cached so subsequent `resolveRepo()` calls don't
+     * re-shell-out to git.
+     */
+    async maybeWarnSiblingDrift(handle) {
+        if (!handle.remoteUrl)
+            return;
+        let cwd;
+        try {
+            cwd = process.cwd();
+        }
+        catch {
+            return;
+        }
+        // Early-exit cache: keyed on (repo, cwd) BEFORE any git shellout.
+        // After the first call for a given cwd, this short-circuits the
+        // up-to-four `execSync`/`execFileSync` calls inside `checkCwdMatch`
+        // — important for MCP-server mode where `process.cwd()` is constant
+        // and `resolveRepo` runs on every tool call.
+        const cacheKey = `${handle.id}|${cwd}`;
+        if (this.warnedSiblingDrift.has(cacheKey))
+            return;
+        const match = await (0, git_staleness_js_1.checkCwdMatch)(cwd);
+        if (match.match !== 'sibling-by-remote' ||
+            !match.entry ||
+            !match.cwdGitRoot ||
+            match.entry.path !== handle.repoPath ||
+            !match.hint) {
+            // Cache "nothing to warn about" outcomes too — `checkCwdMatch`
+            // is deterministic for a fixed (registry, cwd) pair, so re-running
+            // it yields nothing new.
+            this.warnedSiblingDrift.add(cacheKey);
+            return;
+        }
+        this.warnedSiblingDrift.add(cacheKey);
+        logger_js_1.logger.error(`GitNexus: ${match.hint}`);
+    }
+    // ─── Tool Dispatch ───────────────────────────────────────────────
+    /**
+     * #2655: attach a commits-behind freshness signal to a hot-read-tool result,
+     * skipping the `git` spawn entirely for results that can't carry it (error
+     * envelopes, arrays, non-objects — see {@link canCarryStaleness}) so an
+     * error-returning call pays nothing.
+     */
+    async withToolStaleness(repo, result) {
+        if (!canCarryStaleness(result))
+            return result;
+        // Defensive: `checkStalenessAsync` self-catches today, but a rejection here
+        // must never fail the tool — degrade to no-staleness. Paired with the
+        // evict-on-reject in `stalenessForTool`, a transient failure also can't
+        // poison the TTL cache entry (#2655 review F1).
+        const staleness = await this.stalenessForTool(repo).catch(() => undefined);
+        return attachToolStaleness(result, staleness);
+    }
+    /**
+     * #2655: commits-behind freshness for the hot read tools, deduped per index.
+     * Returns a shared in-flight promise so concurrent tool calls spawn at most
+     * one `git rev-list` per index per TTL window; the resolved value is cached
+     * for TOOL_STALENESS_TTL_MS. Keyed by lbugPath so flat and branch handles
+     * (same repoPath, different lastCommit) don't share an entry. Non-blocking by
+     * construction: `checkStalenessAsync` swallows git failures to
+     * `{ isStale: false }`, so a git error never fails the tool — it just omits
+     * the `staleness` field.
+     */
+    stalenessForTool(repo) {
+        const now = Date.now();
+        const cached = this.toolStalenessCache.get(repo.lbugPath);
+        if (cached && now - cached.at < LocalBackend.TOOL_STALENESS_TTL_MS) {
+            return cached.value;
+        }
+        // Evict the entry if the check rejects so a transient failure isn't served
+        // (as a permanently-rejecting promise) for the rest of the TTL window; the
+        // next call then re-runs. A resolving promise is never evicted, so happy-path
+        // dedup is untouched (#2655 review F1). `Promise.resolve` wraps the call so a
+        // non-thenable return can't throw at this boundary — a no-op for the real
+        // async `checkStalenessAsync`, robust defense-in-depth otherwise.
+        const entry = {
+            at: now,
+            // Only evict if THIS entry is still current — a later call may have
+            // installed a fresh (resolving) entry for the same key before a slow
+            // rejection lands, and that newer entry must not be dropped.
+            value: Promise.resolve((0, git_staleness_js_1.checkStalenessAsync)(repo.repoPath, repo.lastCommit)).catch((err) => {
+                if (this.toolStalenessCache.get(repo.lbugPath) === entry) {
+                    this.toolStalenessCache.delete(repo.lbugPath);
+                }
+                throw err;
+            }),
+        };
+        this.toolStalenessCache.set(repo.lbugPath, entry);
+        return entry.value;
+    }
+    async callTool(method, params) {
+        // 已删工具名（query/rename/explain/pdg_query/group_*/list_repos 等）与未知
+        // 工具名一律显式报错，不依赖索引状态、不静默。
+        if (!KNOWN_TOOL_METHODS.has(method)) {
+            return { error: `Unknown tool: ${method}` };
+        }
+        const normalized = normalizeToolParams(method, params);
+        if ('error' in normalized)
+            return { error: normalized.error };
+        const p = normalized.params;
+        // Resolve repo from optional param (re-reads registry on miss). An optional
+        // `branch` param scopes the resolved handle to that branch's index (#2106).
+        const repo = await this.resolveRepo(p.repo, p.branch);
+        switch (method) {
+            case 'cypher': {
+                const raw = await this.cypher(repo, p);
+                return this.withToolStaleness(repo, this.formatCypherAsMarkdown(raw));
+            }
+            case 'context':
+                return this.withToolStaleness(repo, await this.context(repo, p));
+            case 'impact':
+                return this.withToolStaleness(repo, await this.impact(repo, p));
+            case 'detect_changes':
+                return this.detectChanges(repo, p);
+            case 'route_map':
+                return this.routeMap(repo, p);
+            case 'shape_check':
+                return this.shapeCheck(repo, p);
+            case 'tool_map':
+                return this.toolMap(repo, p);
+            case 'api_impact':
+                return this.apiImpact(repo, p);
+            case 'trace':
+                return this.trace(repo, p);
+            default:
+                throw new Error(`Internal: unreachable dispatch for ${method}`);
+        }
+    }
+    // ─── Tool Implementations ────────────────────────────────────────
+    async executeCypher(repoName, query, params = {}) {
+        const repo = await this.resolveRepo(repoName);
+        return this.cypher(repo, { query, params });
+    }
+    async cypher(repo, 
+    // #2175: "statement" is the advertised param; "query" is the legacy alias,
+    // still accepted (and the field the internal executeCypher() passes). New wins.
+    request) {
+        await this.ensureInitialized(repo);
+        if (!(0, pool_adapter_js_1.isLbugReady)(repo.lbugPath)) {
+            return { error: 'LadybugDB not ready. Index may be corrupted.' };
+        }
+        if (request.params !== undefined && !(0, query_params_js_1.isValidQueryParams)(request.params)) {
+            return {
+                error: '"params" must be a plain object with scalar values (string/number/boolean/null).',
+            };
+        }
+        const cypherText = resolveAliasString(request.statement, request.query) ?? '';
+        if (!cypherText.trim()) {
+            // Mirror query()'s friendly required-param error instead of letting an empty
+            // string fall through to a raw LadybugDB prepare error (#2175 review).
+            return { error: 'statement (or legacy query) parameter is required and cannot be empty.' };
+        }
+        try {
+            const result = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, cypherText, request.params ?? {});
+            return result;
+        }
+        catch (err) {
+            const msg = err.message || 'Query failed';
+            if (isReadOnlyDbError(err)) {
+                return {
+                    error: 'Write operations (CREATE, DELETE, SET, MERGE, REMOVE, DROP, ALTER, COPY, DETACH) are not allowed. The knowledge graph is read-only.',
+                };
+            }
+            if ((0, lbug_config_js_1.isWalCorruptionError)(err)) {
+                return {
+                    error: msg,
+                    recoverySuggestion: lbug_config_js_1.WAL_RECOVERY_SUGGESTION,
+                };
+            }
+            return { error: msg };
+        }
+    }
+    /**
+     * Format raw Cypher result rows as a markdown table for LLM readability.
+     * Falls back to raw result if rows aren't tabular objects.
+     */
+    formatCypherAsMarkdown(result) {
+        if (!Array.isArray(result) || result.length === 0)
+            return result;
+        const firstRow = result[0];
+        if (typeof firstRow !== 'object' || firstRow === null)
+            return result;
+        const keys = Object.keys(firstRow);
+        if (keys.length === 0)
+            return result;
+        const header = '| ' + keys.join(' | ') + ' |';
+        const separator = '| ' + keys.map(() => '---').join(' | ') + ' |';
+        const dataRows = result.map((row) => '| ' +
+            keys
+                .map((k) => {
+                const v = row[k];
+                if (v === null || v === undefined)
+                    return '';
+                if (typeof v === 'object')
+                    return JSON.stringify(v);
+                // Collapse newlines so a multi-line cell value (e.g. a symbol's
+                // `content`) stays on one physical line. Otherwise the rendered row
+                // spans multiple lines, which corrupts the table and breaks the
+                // CLI's `--limit` line-based slicing (#2310 review).
+                return String(v).replace(/\r?\n/g, ' ');
+            })
+                .join(' | ') +
+            ' |');
+        return {
+            markdown: [header, separator, ...dataRows].join('\n'),
+            row_count: result.length,
+        };
+    }
+    /**
+     * Aggregate same-named clusters: group by heuristicLabel, sum symbols,
+     * weighted-average cohesion, filter out tiny clusters (<5 symbols).
+     * Raw communities stay intact in LadybugDB for Cypher queries.
+     */
+    aggregateClusters(clusters) {
+        const groups = new Map();
+        for (const c of clusters) {
+            const label = c.heuristicLabel || c.label || 'Unknown';
+            const symbols = c.symbolCount || 0;
+            const cohesion = c.cohesion || 0;
+            const existing = groups.get(label);
+            if (!existing) {
+                groups.set(label, {
+                    ids: [c.id],
+                    totalSymbols: symbols,
+                    weightedCohesion: cohesion * symbols,
+                    largest: c,
+                });
+            }
+            else {
+                existing.ids.push(c.id);
+                existing.totalSymbols += symbols;
+                existing.weightedCohesion += cohesion * symbols;
+                if (symbols > (existing.largest.symbolCount || 0)) {
+                    existing.largest = c;
+                }
+            }
+        }
+        return Array.from(groups.entries())
+            .map(([label, g]) => ({
+            id: g.largest.id,
+            label,
+            heuristicLabel: label,
+            symbolCount: g.totalSymbols,
+            cohesion: g.totalSymbols > 0 ? g.weightedCohesion / g.totalSymbols : 0,
+            subCommunities: g.ids.length,
+        }))
+            .filter((c) => c.symbolCount >= 5)
+            .sort((a, b) => b.symbolCount - a.symbolCount || (0, utils_js_1.compareCodeUnits)(String(a.id), String(b.id)));
+    }
+    /**
+     * Patch the `type` field on candidates whose `labels(n)[0]` projection
+     * came back empty — a known LadybugDB behaviour for several node types.
+     *
+     * Uses one scoped UNION query across the priority labels rather than
+     * per-candidate round-trips, so cost is a single DB call regardless of how
+     * many candidates need enrichment. No-op when every candidate already has a
+     * non-empty type.
+     *
+     * The value labels (`Const` / `Variable` / `Static`) are included because a
+     * value candidate otherwise surfaces with `kind: ""` — which reads as
+     * "unknown kind" and, worse, makes the `kind` disambiguation hint unable to
+     * filter it out (#2687).
+     *
+     * Failures are swallowed: label enrichment is an optimisation for
+     * downstream scoring and #480 Class/Interface BFS seeding; if it fails
+     * the symbol still resolves, just without the kind-priority bonus.
+     */
+    async enrichCandidateLabels(repo, candidates) {
+        const ids = candidates.filter((c) => c.type === '' && c.id).map((c) => c.id);
+        if (ids.length === 0)
+            return;
+        try {
+            const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+        MATCH (n:\`Class\`) WHERE n.id IN $ids RETURN n.id AS id, 'Class' AS label
+        UNION ALL
+        MATCH (n:\`Interface\`) WHERE n.id IN $ids RETURN n.id AS id, 'Interface' AS label
+        UNION ALL
+        MATCH (n:\`Function\`) WHERE n.id IN $ids RETURN n.id AS id, 'Function' AS label
+        UNION ALL
+        MATCH (n:\`Method\`) WHERE n.id IN $ids RETURN n.id AS id, 'Method' AS label
+        UNION ALL
+        MATCH (n:\`Constructor\`) WHERE n.id IN $ids RETURN n.id AS id, 'Constructor' AS label
+        UNION ALL
+        MATCH (n:\`CodeElement\`) WHERE n.id IN $ids RETURN n.id AS id, 'CodeElement' AS label
+        UNION ALL
+        MATCH (n:\`Const\`) WHERE n.id IN $ids RETURN n.id AS id, 'Const' AS label
+        UNION ALL
+        MATCH (n:\`Variable\`) WHERE n.id IN $ids RETURN n.id AS id, 'Variable' AS label
+        UNION ALL
+        MATCH (n:\`Static\`) WHERE n.id IN $ids RETURN n.id AS id, 'Static' AS label
+        `, { ids });
+            const labelById = new Map();
+            for (const r of rows) {
+                const id = (r.id ?? r[0]);
+                const label = (r.label ?? r[1]);
+                if (id && label && !labelById.has(id))
+                    labelById.set(id, label);
+            }
+            for (const c of candidates) {
+                if (c.type === '' && labelById.has(c.id))
+                    c.type = labelById.get(c.id);
+            }
+        }
+        catch {
+            /* best-effort — downstream resolvers still work without the label */
+        }
+    }
+    /**
+     * Score a symbol candidate for disambiguation ranking.
+     *
+     * Deterministic, no DB round-trip:
+     *   - base 0.50
+     *   - +0.40 when file_path hint matches (substring, case-insensitive)
+     *   - +0.20 when kind hint exactly matches the candidate's kind
+     *   - when no kind hint, a small priority bonus (Class > Interface >
+     *     Function > Method > Constructor) to preserve the intuition that
+     *     class-level names are usually what the user wanted.
+     *
+     * Capped at 1.0. Intentionally simple and inspectable — a future v2 can
+     * plug in BM25/embedding signals here without changing the surrounding
+     * resolver shape.
+     */
+    scoreCandidate(c, hints) {
+        let s = 0.5;
+        if (hints.file_path && c.filePath && typeof c.filePath === 'string') {
+            if (c.filePath.toLowerCase().includes(hints.file_path.toLowerCase())) {
+                s += 0.4;
+            }
+        }
+        if (hints.kind && c.kind === hints.kind) {
+            s += 0.2;
+        }
+        if (!hints.kind) {
+            const priority = {
+                Class: 5,
+                Interface: 4,
+                Function: 3,
+                Method: 2,
+                Constructor: 1,
+            };
+            s += (priority[c.kind] ?? 0) * 0.02;
+        }
+        return Math.min(1.0, s);
+    }
+    /**
+     * Shared symbol resolver used by `context` and `impact`.
+     *
+     * Returns one of:
+     *   - `{ kind: 'ok', symbol, resolvedLabel }` — single confident match
+     *     (either direct UID, only one candidate after filtering, Class/
+     *     Constructor collapse, or a top-scoring candidate with a clear gap
+     *     to the runner-up).
+     *   - `{ kind: 'ambiguous', candidates }` — multiple viable matches,
+     *     sorted by score desc. Each candidate carries a relevance score.
+     *   - `{ kind: 'not_found' }` — no matches at all.
+     *
+     * Preserves the #480 Class/Constructor preference: when the only
+     * ambiguity is between a Class and its own Constructor (same name,
+     * same filePath), the Class wins silently.
+     */
+    async resolveSymbolCandidates(repo, query, hints) {
+        const { uid, name, include_content } = query;
+        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}`;
+        // Direct UID — zero-ambiguity path.
+        if (uid) {
+            // determinism: probe — PK-anchored singleton. $uid is a node primary key, so at most one row can match and
+            // the LIMIT never chooses between rows.
+            const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
+            if (rows.length === 0)
+                return { kind: 'not_found' };
+            const r = rows[0];
+            const symbol = {
+                id: (r.id ?? r[0]),
+                name: (r.name ?? r[1]),
+                type: (r.type ?? r[2] ?? ''),
+                filePath: (r.filePath ?? r[3]),
+                startLine: (r.startLine ?? r[4]),
+                endLine: (r.endLine ?? r[5]),
+                ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+            };
+            // Same LadybugDB label-enrichment as the name-based path: a UID
+            // pointing at a Class must still surface `type: 'Class'` so impact's
+            // Class/Interface BFS seed fires. No-op when type is already set.
+            await this.enrichCandidateLabels(repo, [symbol]);
+            return { kind: 'ok', symbol, resolvedLabel: symbol.type };
+        }
+        if (!name)
+            return { kind: 'not_found' };
+        const isQualified = name.includes('/') || name.includes(':');
+        let whereClause;
+        const queryParams = { symName: name };
+        if (hints.file_path) {
+            whereClause = `WHERE n.name = $symName AND n.filePath CONTAINS $filePath`;
+            queryParams.filePath = hints.file_path;
+        }
+        else if (isQualified) {
+            // Parenthesised because the kind filter below is appended with AND, which
+            // binds tighter than OR.
+            whereClause = `WHERE (n.id = $symName OR n.name = $symName)`;
+        }
+        else {
+            whereClause = `WHERE n.name = $symName`;
+        }
+        // A `kind` hint FILTERS, it does not merely score (#2787 review F5). Node
+        // ids are `Label:filePath:qualifiedName`, so the ORDER BY below is a
+        // label-major sort: `Class` < `Const` < `Constructor` < `Function` <
+        // `Interface` < `Method`. A caller asking for kind:'Method' on a name with
+        // many Function/Const homonyms could therefore have every Method sorted out
+        // of the window (`run` has 7 Methods in this repo's index; 2 survive the
+        // ordered page), and scoreCandidate's +0.20 kind bonus can only rank rows
+        // that came back — it can never recover one the LIMIT dropped. The tool
+        // schema already calls this a "Kind filter". Same label-prefix invariant
+        // the ORDER BY depends on, so it costs nothing extra.
+        const kindClause = hints.kind ? `${whereClause} AND n.id STARTS WITH $kindPrefix` : whereClause;
+        const kindParams = hints.kind
+            ? { ...queryParams, kindPrefix: `${hints.kind}:` }
+            : queryParams;
+        // LIMIT CANDIDATE_WINDOW (20; was 10) — scoring is the point now, so give
+        // the ranker headroom instead of arbitrary truncation.
+        //
+        // ORDER BY n.id is load-bearing, not cosmetic (#2787). A bare `LIMIT`
+        // hands back an ARBITRARY subset when more nodes share the name than the
+        // cap (`constructor` = 92 in this repo's own index, `get` = 34), and
+        // LadybugDB picks a different subset from one process to the next — so
+        // `impact`/`context` resolved a different symbol on every invocation and
+        // the HIGH/CRITICAL warning the agent workflow depends on fired at random.
+        // `n.id` is the PRIMARY KEY on every node table: non-null, unique, and a
+        // total order, which is what pins WHICH rows come back.
+        //
+        // `labels(n)[0]` is not an alternative ordering key: it comes back empty for
+        // Class nodes (see enrichCandidateLabels below), so ordering on the
+        // projected type would sort the HIGHEST-priority kind into the empty bucket.
+        //
+        // The COUNT reports the TRUE total, which a LIMIT-capped page's row count
+        // cannot stand in for (#2084 review P2-4). Without it every "Found N symbols
+        // matching 'x'" message and the `totalCandidates` field report the cap, so
+        // 92 collisions read as 20 — and now that the window is ordered, that
+        // undercount is stable, which makes it look authoritative rather than flaky.
+        //
+        // It runs AFTER the window rather than alongside it because a SHORT page
+        // proves the LIMIT never bound, which makes `COUNT(*)` identically
+        // `rows.length`. The COUNT is unlabeled and `n.name` is unindexed, so it is
+        // a full scan of every node table — skipping it halves the cost of the
+        // hottest step in `context`/`impact`/`trace` (`trace` resolves twice).
+        // Trade-off: the full-window (>= CANDIDATE_WINDOW
+        // homonyms) minority path is now sequential instead of concurrent.
+        const fetchWindow = async (where, params) => {
+            const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (n) ${where} RETURN ${selectClause} ORDER BY n.id LIMIT ${CANDIDATE_WINDOW}`, params);
+            if (rows.length < CANDIDATE_WINDOW)
+                return { rows, countedTotal: rows.length };
+            const countRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (n) ${where} RETURN COUNT(*) AS total`, params).catch((e) => {
+                // Never swallowed (#2787 review F3): a failed COUNT falls through to
+                // the window-length floor below, and without a signal the response
+                // ships `totalCandidates: 20` with no `candidatesTruncated` — byte
+                // identical to a genuine 20-match result. `totalIsLowerBound` is the
+                // caller-visible degradation this log is contracted to accompany.
+                logQueryError('resolve:candidate-count', e);
+                return [];
+            });
+            return {
+                rows,
+                countedTotal: Number(countRows[0]?.total ?? countRows[0]?.[0] ?? Number.NaN),
+            };
+        };
+        let { rows, countedTotal } = await fetchWindow(kindClause, kindParams);
+        if (rows.length === 0 && hints.kind) {
+            // `kind` is a free-form string on the tool schema, so a hint that matches
+            // no label prefix (wrong case, or a kind this repo has no nodes for) must
+            // not turn a real name into `not_found`. Fall back to the unfiltered
+            // window and let scoreCandidate treat the hint as a ranking term, exactly
+            // as it did before the filter existed.
+            ({ rows, countedTotal } = await fetchWindow(whereClause, queryParams));
+        }
+        if (rows.length === 0)
+            return { kind: 'not_found' };
+        // Normalise row shape across object / tuple returns from LadybugDB.
+        const normalized = rows.map((r) => ({
+            id: (r.id ?? r[0]),
+            name: (r.name ?? r[1]),
+            type: (r.type ?? r[2] ?? ''),
+            filePath: (r.filePath ?? r[3]),
+            startLine: (r.startLine ?? r[4]),
+            endLine: (r.endLine ?? r[5]),
+            ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+        }));
+        // The COUNT can never legitimately be below the page it accompanies, so a
+        // value under `normalized.length` means the count leg failed or returned an
+        // unreadable shape. Keep the window size as the floor — reporting zero would
+        // be worse — but mark the number a LOWER BOUND so no consumer treats it as
+        // the exact match count this PR otherwise promises (#2787 review F3).
+        const totalIsExact = Number.isFinite(countedTotal) && countedTotal >= normalized.length;
+        const totalMatches = totalIsExact ? countedTotal : normalized.length;
+        // Enrich labels for any candidates where `labels(n)[0]` came back empty.
+        // LadybugDB returns an empty string for that projection on certain node
+        // types (notably Class), which left downstream consumers (impact's
+        // Class/Interface BFS seed, the kind-priority scoring bonus) unable to
+        // distinguish a Class target from "unknown kind". One scoped UNION
+        // across the priority labels patches the type in-place without
+        // per-candidate round-trips.
+        await this.enrichCandidateLabels(repo, normalized);
+        // Preserve #480 Class/Constructor collapse: if we have exactly one
+        // Class (or Interface) candidate and one Constructor sharing name +
+        // filePath, fold into the Class. This used to require a follow-up
+        // label query because LadybugDB sometimes returns an empty labels()[0]
+        // for Class nodes — enrichment above handles the empty-type case, but
+        // the `type === 'Constructor'` gate still correctly triggers when a
+        // Class and its Constructor share the name.
+        if (!hints.kind && normalized.length > 1) {
+            // A value candidate (`Const`/`Variable`/`Static`) used to reach here with
+            // `type === ''`, which is what kept this gate true for a `class Foo` +
+            // `const Foo` pair and let the collapse resolve it to the Class. Label
+            // enrichment now fills those in (#2687), so they must be named explicitly
+            // or the collapse silently stops firing and confident resolutions become
+            // `ambiguous` across every resolver-backed tool.
+            const ambiguousType = normalized.some((s) => s.type === '' || s.type === 'Constructor' || VALUE_CANDIDATE_TYPES.has(s.type));
+            // Collapsing is a CONFIDENT resolution — it returns `kind: 'ok'` and the
+            // caller never sees the scorer or the ambiguity report — so it may only
+            // fire when the label match is genuinely unique (#2787 review F4).
+            // Ordering the probe made the wrong pick repeatable; it did not make it
+            // right. Two same-named classes in two files is routine, and this is the
+            // only confident path a bare name can take (scoreCandidate tops out at
+            // 0.60 without a file_path hint, the confident gate below needs >= 0.95),
+            // so an arbitrary winner here is `context`/`impact` silently analysing the
+            // wrong file. A window that was itself truncated is disqualifying for the
+            // same reason: a candidate outside the page could carry the label too.
+            const windowIsComplete = normalized.length < CANDIDATE_WINDOW || (totalIsExact && totalMatches <= normalized.length);
+            if (ambiguousType && windowIsComplete) {
+                const candidateIds = normalized.map((s) => s.id).filter(Boolean);
+                for (const label of ['Class', 'Interface']) {
+                    // LIMIT 2, not 1: the second row is the uniqueness check. One row back
+                    // means exactly one candidate carries the label and the collapse is
+                    // safe; two means fall through to normal ambiguity scoring.
+                    const labelRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id ORDER BY n.id LIMIT 2`, { candidateIds }).catch(() => []);
+                    if (labelRows.length === 1) {
+                        const preferredId = labelRows[0].id ?? labelRows[0][0];
+                        const preferred = normalized.find((s) => s.id === preferredId);
+                        if (preferred) {
+                            return {
+                                kind: 'ok',
+                                symbol: preferred,
+                                resolvedLabel: label,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+        if (normalized.length === 1) {
+            return {
+                kind: 'ok',
+                symbol: normalized[0],
+                resolvedLabel: '',
+            };
+        }
+        // Score, sort desc, stable tiebreak on shorter filePath then lex uid.
+        const scored = normalized.map((s) => ({
+            ...s,
+            score: this.scoreCandidate({ kind: s.type, filePath: s.filePath || '' }, hints),
+        }));
+        scored.sort((a, b) => {
+            if (b.score !== a.score)
+                return b.score - a.score;
+            const fpA = (a.filePath || '').length;
+            const fpB = (b.filePath || '').length;
+            if (fpA !== fpB)
+                return fpA - fpB;
+            return (0, utils_js_1.compareCodeUnits)(String(a.id), String(b.id));
+        });
+        // Confident single-result: top score ≥ 0.95 AND beats runner-up by a
+        // clear margin. This lets a very strong file_path/kind hint resolve
+        // cleanly instead of forcing the caller through a disambiguation
+        // round-trip.
+        //
+        // The gap threshold uses `> 0.09` rather than `>= 0.10` on purpose:
+        // IEEE754 addition of the scoring terms (0.50 + 0.40 + 0.20 - 0.90
+        // yields 0.09999999999999998, not exactly 0.10) would otherwise break
+        // the comparison for legitimate "top is 1.00, runner is 0.90" cases.
+        // The intent is a clearly-dominant winner; 0.09 is a large enough
+        // margin to mean that unambiguously.
+        //
+        // The `scored.length >= 2` guard is defensive. The `normalized.length === 1`
+        // early return above already handles the single-candidate path, so in
+        // practice `scored` always has at least two elements by the time we get
+        // here — keeping the guard means changes to the upstream early-return
+        // logic cannot accidentally index out of bounds at `scored[1]`.
+        if (scored.length >= 2 && scored[0].score >= 0.95 && scored[0].score - scored[1].score > 0.09) {
+            return { kind: 'ok', symbol: scored[0], resolvedLabel: scored[0].type };
+        }
+        return {
+            kind: 'ambiguous',
+            candidates: scored,
+            total: totalMatches,
+            ...(totalIsExact ? {} : { totalIsLowerBound: true }),
+        };
+    }
+    /**
+     * Context tool — 360-degree symbol view with categorized refs.
+     * Disambiguation (ranked) when multiple symbols share a name.
+     * UID-based direct lookup. No cluster in output.
+     */
+    async context(repo, params) {
+        try {
+            return await this._contextImpl(repo, params);
+        }
+        catch (err) {
+            const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
+            if ((0, lbug_config_js_1.isWalCorruptionError)(err)) {
+                return {
+                    error: msg,
+                    recoverySuggestion: lbug_config_js_1.WAL_RECOVERY_SUGGESTION,
+                };
+            }
+            throw err;
+        }
+    }
+    async _contextImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        const { name, uid, file_path, kind, include_content } = params;
+        if (!name && !uid) {
+            return { error: 'Either "name" or "uid" parameter is required.' };
+        }
+        const outcome = await this.resolveSymbolCandidates(repo, { uid, name, include_content }, { file_path, kind });
+        if (outcome.kind === 'not_found') {
+            return { error: `Symbol '${name || uid}' not found` };
+        }
+        if (outcome.kind === 'ambiguous') {
+            const { atLeast, showing, fields } = ambiguityReport(outcome, outcome.candidates.length);
+            return {
+                status: 'ambiguous',
+                message: `Found ${atLeast}${outcome.total} symbols matching '${name}'${showing}. Use uid, file_path, or kind to disambiguate.`,
+                ...fields,
+                candidates: outcome.candidates.map((c) => ({
+                    uid: c.id,
+                    name: c.name,
+                    kind: c.type,
+                    filePath: c.filePath,
+                    line: (0, line_display_js_1.toDisplayLine)(c.startLine),
+                    score: Number(c.score.toFixed(2)),
+                })),
+            };
+        }
+        // Step 3: Build full context
+        const sym = outcome.symbol;
+        const resolvedLabel = outcome.resolvedLabel;
+        const symId = sym.id;
+        // Categorized incoming refs.
+        //
+        // ORDER BY uid, relType — the CATEGORY column must NOT lead (#2787 review
+        // F1). With `relType` first the 30-row window fills in alphabetical
+        // category order, so any category whose alphabetical predecessors already
+        // total 30 is dropped in 100% of runs: a symbol with {ACCESSES:3, CALLS:35,
+        // USES:1, HAS_METHOD:1} came back as {ACCESSES:3, CALLS:27} — HAS_METHOD
+        // (which names the owning class) and USES simply gone, and categorize()
+        // below emits whatever buckets it is handed with no truncation flag, so the
+        // loss is silent. Leading with `uid` (a node primary key) is still a total
+        // order and still deterministic, but it spreads the window across
+        // categories the way the unordered scan incidentally did.
+        const [incomingRows, incomingAdvisedRows] = await Promise.all([
+            (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES', 'RCALLS', 'HTTP_CALLS']
+      RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+      ORDER BY uid, relType
+      LIMIT 30
+    `, { symId }),
+            // Keep high-fan-in advice edges out of the legacy 30-row context window.
+            // A broad pointcut can advise hundreds of methods; sharing that LIMIT
+            // would make CALLS/HAS_METHOD/etc. disappear nondeterministically.
+            // Splitting the window bounded that; ORDER BY finishes the job (#2787) —
+            // an unordered LIMIT still let the surviving 30 change per process, and
+            // these rows reach the response in query order via categorize().
+            (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (caller)-[r:CodeRelation {type: 'ADVISED_BY'}]->(n {id: $symId})
+      RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+      ORDER BY uid
+      LIMIT 30
+    `, { symId }),
+        ]);
+        incomingRows.push(...incomingAdvisedRows);
+        let typedPropertyRows = [];
+        // Fix #480: Class/Interface nodes have no direct CALLS/IMPORTS edges —
+        // those point to Constructor and File nodes respectively. Fetch those
+        // extra incoming refs and merge them in so context() shows real callers.
+        //
+        // Determine if this is a Class/Interface node. If resolvedLabel was set
+        // during disambiguation (Step 2), use it directly — no extra round-trip.
+        // Otherwise fall back to a single label check only when the type field is
+        // empty (LadybugDB labels(n)[0] limitation).
+        const symRawType = sym.type || sym[2] || '';
+        let isClassLike = resolvedLabel === 'Class' || resolvedLabel === 'Interface';
+        if (!isClassLike && symRawType === '') {
+            try {
+                // Single UNION query instead of two serial round-trips.
+                // determinism: probe — existence only, and each UNION branch is PK-anchored on $symId. Only typeCheck.length
+                // > 0 is read; the projected label is discarded.
+                const typeCheck = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+          MATCH (n:Class) WHERE n.id = $symId RETURN 'Class' AS label LIMIT 1
+          UNION ALL
+          MATCH (n:Interface) WHERE n.id = $symId RETURN 'Interface' AS label LIMIT 1
+        `, { symId });
+                isClassLike = typeCheck.length > 0;
+            }
+            catch {
+                /* not a Class/Interface node */
+            }
+        }
+        else if (!isClassLike) {
+            isClassLike = symRawType === 'Class' || symRawType === 'Interface';
+        }
+        if (isClassLike) {
+            try {
+                // Run incoming-ref queries in parallel — they are independent.
+                const [ctorIncoming, fileIncoming, typedPropertyIncoming, typedProperties] = await Promise.all([
+                    (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (n)-[hm:CodeRelation]->(ctor:Constructor)
+            WHERE n.id = $symId AND hm.type = 'HAS_METHOD'
+            MATCH (caller)-[r:CodeRelation]->(ctor)
+            WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'ACCESSES', 'RCALLS', 'HTTP_CALLS']
+            RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+            ORDER BY uid, relType
+            LIMIT 30
+          `, { symId }),
+                    (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (f:File)-[rel:CodeRelation]->(n)
+            WHERE n.id = $symId AND rel.type = 'DEFINES'
+            MATCH (caller)-[r:CodeRelation]->(f)
+            WHERE r.type IN ['CALLS', 'IMPORTS', 'RCALLS', 'HTTP_CALLS']
+            RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+            ORDER BY uid, relType
+            LIMIT 30
+          `, { symId }),
+                    (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (p:\`Property\`)
+            WHERE p.declaredType = $name
+               OR p.declaredType STARTS WITH $genericPrefix
+               OR p.declaredType CONTAINS $genericArg
+            MATCH (caller)-[r:CodeRelation]->(p)
+            WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'ACCESSES', 'RCALLS', 'HTTP_CALLS']
+            RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
+            ORDER BY uid, relType
+            LIMIT 30
+          `, {
+                        name: sym.name,
+                        genericPrefix: `${sym.name}<`,
+                        genericArg: `<${sym.name}>`,
+                    }),
+                    (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (p:\`Property\`)
+            WHERE p.declaredType = $name
+               OR p.declaredType STARTS WITH $genericPrefix
+               OR p.declaredType CONTAINS $genericArg
+            RETURN p.id AS uid, p.name AS name, p.filePath AS filePath, labels(p)[0] AS kind,
+                   p.declaredType AS declaredType
+            ORDER BY uid
+            LIMIT 30
+          `, {
+                        name: sym.name,
+                        genericPrefix: `${sym.name}<`,
+                        genericArg: `<${sym.name}>`,
+                    }),
+                ]);
+                typedPropertyRows = typedProperties;
+                // Deduplicate by (relType, uid) — a caller can have multiple relation
+                // types to the same target (e.g. both IMPORTS and CALLS), and each
+                // must be preserved so every category appears in the output.
+                const seenKeys = new Set(incomingRows.map((r) => `${r.relType || r[0]}:${r.uid || r[1]}`));
+                for (const r of [...ctorIncoming, ...fileIncoming, ...typedPropertyIncoming]) {
+                    const key = `${r.relType || r[0]}:${r.uid || r[1]}`;
+                    if (!seenKeys.has(key)) {
+                        seenKeys.add(key);
+                        incomingRows.push(r);
+                    }
+                }
+            }
+            catch (e) {
+                logQueryError('context:class-incoming-expansion', e);
+            }
+        }
+        // Categorized outgoing refs. uid-major for the same reason as the incoming
+        // window above — a category-major key starves whole buckets (#2787 F1).
+        const [outgoingRows, outgoingAdvisedRows] = await Promise.all([
+            (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (n {id: $symId})-[r:CodeRelation]->(target)
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES', 'RCALLS', 'HTTP_CALLS']
+      RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
+      ORDER BY uid, relType
+      LIMIT 30
+    `, { symId }),
+            (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (n {id: $symId})-[r:CodeRelation {type: 'ADVISED_BY'}]->(target)
+      RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
+      ORDER BY uid
+      LIMIT 30
+    `, { symId }),
+        ]);
+        outgoingRows.push(...outgoingAdvisedRows);
+        // Process participation.
+        //
+        // MIN(r.step) enforces one row per process (#2787). It is behaviour
+        // preserving on today's data — a full scan of this repo's index puts the
+        // maximum STEP_IN_PROCESS edge count for any (symbol, process) pair at 1 —
+        // but nothing in the schema caps it there, and `processes` is the only
+        // uncapped number in this response, so a symbol that ever picks up a second
+        // step edge would silently report an edge count instead of a process count.
+        // Aggregating makes the one-row-per-process invariant explicit rather than
+        // inherited from the data, and matches _runImpactBFS's twin query.
+        let processRows = [];
+        try {
+            processRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+        MATCH (n {id: $symId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+        RETURN p.id AS pid, p.heuristicLabel AS label, MIN(r.step) AS step, p.stepCount AS stepCount
+        ORDER BY pid
+      `, { symId });
+        }
+        catch (e) {
+            logQueryError('context:process-participation', e);
+        }
+        // Helper to categorize refs
+        const categorize = (rows) => {
+            const cats = {};
+            for (const row of rows) {
+                const relType = (row.relType || row[0] || '').toLowerCase();
+                const entry = {
+                    uid: row.uid || row[1],
+                    name: row.name || row[2],
+                    filePath: row.filePath || row[3],
+                    kind: row.kind || row[4],
+                };
+                if (!cats[relType])
+                    cats[relType] = [];
+                cats[relType].push(entry);
+            }
+            return cats;
+        };
+        // Method/Function/Constructor enrichment: fetch method-specific properties
+        const symKind = isClassLike ? resolvedLabel || 'Class' : sym.type || sym[2];
+        const isMethodLike = symKind === 'Method' || symKind === 'Function' || symKind === 'Constructor';
+        // #1858 review F2 — start the epistemic boundary probe here (right after
+        // `symKind` is known) so it runs CONCURRENTLY with the methodMetadata fetch
+        // below, mirroring how _runImpactBFS overlaps it with the BFS. It is awaited
+        // at result assembly. (It cannot start earlier — `symKind` is only computed
+        // on this line, after the incoming/outgoing round-trips.)
+        //
+        // #1858 review F3 — pass an interface-preserving type, NOT `symKind`.
+        // `symKind` collapses a single-resolved Interface to 'Class' (resolvedLabel
+        // is '' on the single-candidate path), which would skip computeEpistemicBoundary's
+        // `symType === 'Interface'` self-boundary branch and under-report a leaf
+        // interface as 'exact'. `enrichCandidateLabels` runs BEFORE the single-candidate
+        // early return and patches `sym.type` from '' to 'Interface' (LadybugDB returns
+        // '' for labels()[0] on Interface/Class), so `sym.type` is the reliable signal
+        // here — mirroring impact()'s `resolvedLabel || symbol.type` derivation. Do not
+        // "fix" enrichment ordering; F3 depends on enrichment-before-early-return.
+        const epistemicSymType = (resolvedLabel || sym.type || symKind || '');
+        const epistemicPromise = this.computeEpistemicBoundary(repo, symId, epistemicSymType, (sym.name || sym[1]));
+        const beanMetadataPromise = (0, bean_metadata_js_1.queryClassBeanMetadata)(repo.lbugPath, symId, epistemicSymType);
+        const aopMetadataPromise = (0, aop_metadata_js_1.querySpringAopMetadata)(repo.lbugPath, symId, epistemicSymType);
+        let methodMetadata;
+        if (isMethodLike) {
+            try {
+                // determinism: probe — PK-anchored singleton. $symId is a node primary key, so at most one row of method
+                // metadata can match.
+                const metaRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+          MATCH (n {id: $symId})
+          RETURN n.visibility AS visibility, n.isStatic AS isStatic, n.isAbstract AS isAbstract,
+                 n.isFinal AS isFinal, n.isVirtual AS isVirtual, n.isOverride AS isOverride,
+                 n.isAsync AS isAsync, n.isPartial AS isPartial, n.returnType AS returnType,
+                 n.parameterCount AS parameterCount, n.isVariadic AS isVariadic,
+                 n.requiredParameterCount AS requiredParameterCount,
+                 n.parameterTypes AS parameterTypes, n.annotations AS annotations
+          LIMIT 1
+        `, { symId });
+                if (metaRows.length > 0) {
+                    const row = metaRows[0];
+                    const meta = {};
+                    // Only include defined properties to distinguish "not applicable" from "not enriched"
+                    for (const key of Object.keys(row)) {
+                        const val = row[key];
+                        if (val !== null && val !== undefined)
+                            meta[key] = val;
+                    }
+                    if (Object.keys(meta).length > 0)
+                        methodMetadata = meta;
+                }
+            }
+            catch {
+                /* method metadata unavailable — omit silently */
+            }
+        }
+        // #1858 — same epistemic boundary signal as impact(): when this symbol sits
+        // behind an interface / indirection boundary, callers binding via DI or
+        // dynamic dispatch are not reflected in `incoming`, so the view is a lower
+        // bound. Additive; never suppresses a field. Resolved from the probe started
+        // above (concurrent with methodMetadata).
+        const [epistemic, beanMetadata, aopMetadata] = await Promise.all([
+            epistemicPromise,
+            beanMetadataPromise,
+            aopMetadataPromise,
+        ]);
+        return {
+            status: 'found',
+            symbol: {
+                uid: sym.id || sym[0],
+                name: sym.name || sym[1],
+                kind: symKind,
+                filePath: sym.filePath || sym[3],
+                startLine: (0, line_display_js_1.toDisplayLine)(sym.startLine ?? sym[4]),
+                endLine: (0, line_display_js_1.toDisplayLine)(sym.endLine ?? sym[5]),
+                ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
+                ...(methodMetadata ? { methodMetadata } : {}),
+                ...(beanMetadata ? { bean: beanMetadata } : {}),
+                ...(aopMetadata ? { aop: aopMetadata } : {}),
+            },
+            ...epistemic,
+            incoming: categorize(incomingRows),
+            outgoing: categorize(outgoingRows),
+            ...(typedPropertyRows.length > 0
+                ? {
+                    typed_properties: typedPropertyRows.map((r) => ({
+                        uid: r.uid || r[0],
+                        name: r.name || r[1],
+                        filePath: r.filePath || r[2],
+                        kind: r.kind || r[3],
+                        declaredType: r.declaredType || r[4],
+                    })),
+                }
+                : {}),
+            processes: processRows.map((r) => ({
+                id: r.pid || r[0],
+                name: r.label || r[1],
+                step_index: r.step || r[2],
+                step_count: r.stepCount || r[3],
+            })),
+        };
+    }
+    /**
+     * Detect changes — git-diff based impact analysis.
+     * Maps changed lines to indexed symbols, then finds affected processes.
+     */
+    async detectChanges(repo, params) {
+        await this.ensureInitialized(repo);
+        const scope = params.scope || 'unstaged';
+        // Ignore CR-only EOL differences, while preserving meaningful whitespace changes.
+        // execFileSync receives an argv array, so refs never pass through a shell.
+        const diffArgs = buildDetectChangesDiffArgs(scope, params.base_ref);
+        if (!diffArgs)
+            return { error: 'base_ref is required for "compare" scope' };
+        // Resolve the cwd for git diff (worktree handling — see resolveWorktreeCwd).
+        //
+        // diffCwd 即"聚合根":单仓场景下等于仓库根,多 git 子工程场景下是那层非 git
+        // 的项目根。两种情况下索引里的 filePath 都相对它存储(filesystem-walker 以
+        // repoPath 为基准),因此子工程 diff 路径需补该前缀才能命中符号(T-13b)。
+        //
+        // Resolution order (see resolveWorktreeCwd for details):
+        //   1. params.worktree — explicit override, validated against the
+        //      registered repo's canonical root.
+        //   2. Auto-detect — if the server's launch cwd (process.cwd()) is a
+        //      linked worktree of the same canonical repo, use its git root.
+        //   3. repo.repoPath — fallback (original behaviour, handled inside
+        //      resolveWorktreeCwd when no worktree is detected).
+        let diffCwd = resolveWorktreeCwd(repo.repoPath, process.cwd());
+        if (params.worktree) {
+            if (!path_1.default.isAbsolute(params.worktree)) {
+                return {
+                    error: `worktree must be an absolute path, got: "${params.worktree}"`,
+                };
+            }
+            const providedResolved = path_1.default.resolve(params.worktree);
+            const repoCanonical = (0, git_js_1.getCanonicalRepoRoot)(repo.repoPath);
+            if (!repoCanonical) {
+                return {
+                    error: `Could not determine canonical root for repo "${repo.repoPath}". Is git available?`,
+                };
+            }
+            const worktreeCanonical = (0, git_js_1.getCanonicalRepoRoot)(providedResolved);
+            if (!worktreeCanonical || tryRealpath(worktreeCanonical) !== tryRealpath(repoCanonical)) {
+                return {
+                    error: `worktree "${params.worktree}" is not a worktree of repo "${repo.repoPath}". Ensure the path is inside the same git repository.`,
+                };
+            }
+            diffCwd = providedResolved;
+        }
+        let fileDiffs;
+        // 子工程采集失败(如 compare 缺 base-ref):逐项记录说明,不整体失败(spec §4)。
+        const subprojectErrors = [];
+        try {
+            if ((0, git_js_1.isGitRepo)(diffCwd)) {
+                // 单仓路径(基线):diffCwd 即仓库根,git diff 输出的 filePath 已相对该根。
+                fileDiffs = await collectDetectChangesFileDiffs(diffCwd, diffArgs);
+            }
+            else {
+                // 聚合根非 git(spec §4 / T-13b):发现一级 git 子工程,逐个按其自身 git
+                // 状态采集变更,合并映射为受影响符号与执行流。scope/base-ref 语义对每个
+                // 子工程一致适用;某子工程缺 base-ref 等失败记入 subprojectErrors。
+                const subprojects = discoverGitSubprojects(diffCwd);
+                if (subprojects.length === 0) {
+                    // 根与各子工程均无 git → 明确报错(spec §9,T-13 守卫保留此路径)。
+                    return {
+                        error: '[cgraph] detect-changes 需要 git 工作树。该索引为纯目录(无 .git)且未发现 git 子工程——变更检测不可用。',
+                    };
+                }
+                const collected = await collectSubprojectFileDiffs(diffCwd, subprojects, diffArgs);
+                fileDiffs = collected.fileDiffs;
+                subprojectErrors.push(...collected.errors);
+            }
+        }
+        catch (err) {
+            return { error: `Git diff failed: ${err.message}` };
+        }
+        if (fileDiffs.length === 0) {
+            return {
+                summary: {
+                    changed_count: 0,
+                    affected_count: 0,
+                    risk_level: 'none',
+                    message: 'No changes detected.',
+                },
+                changed_symbols: [],
+                affected_processes: [],
+                // 子工程采集失败时即便无变更也要把失败说明带出去,避免假"干净"。
+                ...(subprojectErrors.length > 0 && { subproject_errors: subprojectErrors }),
+            };
+        }
+        // Map diff hunks to indexed symbols via range overlap
+        const changedSymbols = [];
+        // Set if a swallowed graph query fails below — surfaces `partial:true` so a
+        // degraded run cannot report a false-clean `risk_level:'low'` (#2283).
+        let queryDegraded = false;
+        for (const fileDiff of fileDiffs) {
+            if (fileDiff.hunks.length === 0)
+                continue;
+            // Build range overlap conditions for all hunks in this file
+            const overlapConditions = fileDiff.hunks
+                .map((_, i) => `(n.startLine <= $hunkEnd${i} AND n.endLine >= $hunkStart${i})`)
+                .join(' OR ');
+            const queryParams = { filePath: fileDiff.filePath };
+            fileDiff.hunks.forEach((hunk, i) => {
+                queryParams[`hunkStart${i}`] = hunk.startLine;
+                queryParams[`hunkEnd${i}`] = hunk.endLine;
+            });
+            // Exclude BasicBlock rows by id prefix: on a --pdg index every edited
+            // function otherwise contributes N nameless BasicBlock pseudo-"symbols"
+            // (they carry filePath/start/end but no name), inflating changed_count
+            // and risk level with rows no consumer can act on (#2082 U7). Blocks
+            // are implementation substrate, not symbols — the owning Function row
+            // already represents the change. The id prefix (`BasicBlock:<file>:…`,
+            // cfg/emit.ts basicBlockId) beats a label predicate (`labels(n)[0]` is
+            // known to come back empty for several node types — see
+            // enrichCandidateLabels) AND beats `n.name IS NOT NULL` (which would
+            // also drop legitimate symbols whose name loaded as NULL, e.g.
+            // quoted-empty CSV fields for anonymous constructs).
+            const symbolQuery = `
+        MATCH (n) WHERE n.filePath ENDS WITH $filePath
+          AND NOT n.id STARTS WITH 'BasicBlock:'
+          AND n.startLine IS NOT NULL AND n.endLine IS NOT NULL
+          AND (${overlapConditions})
+        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type,
+               n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+      `;
+            try {
+                const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, symbolQuery, queryParams);
+                for (const sym of rows) {
+                    changedSymbols.push({
+                        id: sym.id || sym[0],
+                        name: sym.name || sym[1],
+                        type: sym.type || sym[2],
+                        filePath: sym.filePath || sym[3],
+                        change_type: 'touched',
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('detect-changes:file-symbols', e);
+                // The symbol query failed: changedSymbols stays empty and the result
+                // would otherwise look like a clean no-op (`changed_count:0`,
+                // `risk_level:'low'`). detect_changes is the pre-commit safety gate, so
+                // flag the result `partial` rather than let a swallowed failure
+                // masquerade as "nothing changed" (#2283).
+                queryDegraded = true;
+            }
+        }
+        // Find affected processes -- single batched query instead of N+1
+        const affectedProcesses = new Map();
+        if (changedSymbols.length > 0) {
+            const symIds = changedSymbols.map((s) => s.id);
+            const symNameById = new Map(changedSymbols.map((s) => [s.id, s.name]));
+            try {
+                const procs = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+          MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE n.id IN $ids
+          RETURN n.id AS nodeId, p.id AS pid, p.heuristicLabel AS label,
+                 p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `, { ids: symIds });
+                for (const proc of procs) {
+                    const nodeId = proc.nodeId || proc[0];
+                    const pid = proc.pid || proc[1];
+                    if (!affectedProcesses.has(pid)) {
+                        affectedProcesses.set(pid, {
+                            id: pid,
+                            name: proc.label || proc[2],
+                            process_type: proc.processType || proc[3],
+                            step_count: proc.stepCount || proc[4],
+                            changed_steps: [],
+                        });
+                    }
+                    affectedProcesses.get(pid).changed_steps.push({
+                        symbol: symNameById.get(nodeId) ?? nodeId,
+                        step: proc.step || proc[5],
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('detect-changes:process-lookup', e);
+                queryDegraded = true;
+            }
+        }
+        const processCount = affectedProcesses.size;
+        const risk = processCount === 0
+            ? 'low'
+            : processCount <= 5
+                ? 'medium'
+                : processCount <= 15
+                    ? 'high'
+                    : 'critical';
+        return {
+            summary: {
+                changed_count: changedSymbols.length,
+                affected_count: processCount,
+                changed_files: fileDiffs.length,
+                risk_level: risk,
+            },
+            changed_symbols: changedSymbols,
+            affected_processes: Array.from(affectedProcesses.values()),
+            // A swallowed query failure makes the counts/risk above incomplete — tell
+            // the caller so the safety gate isn't trusted as a clean result (#2283).
+            ...(queryDegraded && { partial: true }),
+            // 聚合根多 git 子工程场景(T-13b):逐子工程采集时,某子工程失败(典型为
+            // compare 的 base-ref 在该子工程不存在)在此带出而非整体失败(spec §4)。
+            ...(subprojectErrors.length > 0 && { subproject_errors: subprojectErrors }),
+        };
+    }
+    async trace(repo, params) {
+        try {
+            return await this._traceImpl(repo, params);
+        }
+        catch (err) {
+            return {
+                status: 'error',
+                error: (err instanceof Error ? err.message : String(err)) || 'Trace analysis failed',
+                from: { name: params.from },
+                to: { name: params.to },
+                suggestion: 'The graph query failed — try cgraph context <symbol> to see connections, ' +
+                    'or check if an interface bridges them.',
+                ...((0, lbug_config_js_1.isWalCorruptionError)(err) ? { recoverySuggestion: lbug_config_js_1.WAL_RECOVERY_SUGGESTION } : {}),
+            };
+        }
+    }
+    async _traceImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        // resolveSymbolCandidates feeds `from`/`to` into string operations
+        // (e.g. name.includes), so a non-string param would surface a low-level
+        // "x.includes is not a function". Reject it with a clear message instead.
+        const isStringOrAbsent = (v) => v === undefined || typeof v === 'string';
+        if (!isStringOrAbsent(params.from) ||
+            !isStringOrAbsent(params.to) ||
+            !isStringOrAbsent(params.from_uid) ||
+            !isStringOrAbsent(params.to_uid)) {
+            return {
+                status: 'error',
+                error: "'from', 'to', and their *_uid variants must be strings.",
+                suggestion: 'Pass symbol names or UIDs as strings, e.g. trace from="A" to="B".',
+            };
+        }
+        // A trace needs a target — reject a to-less call with an actionable error
+        // rather than the opaque "Target symbol 'undefined' not found".
+        const hasTo = (typeof params.to === 'string' && params.to.trim() !== '') ||
+            (typeof params.to_uid === 'string' && params.to_uid.trim() !== '');
+        if (!hasTo) {
+            return {
+                status: 'error',
+                error: 'trace requires `to` (or `to_uid`).',
+                suggestion: 'Pass a target symbol name or UID.',
+            };
+        }
+        const fromOutcome = await this.resolveSymbolCandidates(repo, { uid: params.from_uid, name: params.from }, { file_path: params.from_file });
+        if (fromOutcome.kind === 'not_found') {
+            return {
+                status: 'not_found',
+                error: `Source symbol '${params.from_uid ?? params.from}' not found.`,
+                suggestion: 'Check the symbol name or use --from-uid for zero-ambiguity.',
+            };
+        }
+        if (fromOutcome.kind === 'ambiguous') {
+            const { atLeast, showing, fields } = ambiguityReport(fromOutcome, fromOutcome.candidates.length);
+            return {
+                status: 'ambiguous',
+                role: 'from',
+                message: `Found ${atLeast}${fromOutcome.total} symbols matching '${params.from}'${showing}. Disambiguate with --from-uid.`,
+                ...fields,
+                candidates: fromOutcome.candidates,
+            };
+        }
+        const toOutcome = await this.resolveSymbolCandidates(repo, { uid: params.to_uid, name: params.to }, { file_path: params.to_file });
+        if (toOutcome.kind === 'not_found') {
+            return {
+                status: 'not_found',
+                error: `Target symbol '${params.to_uid ?? params.to}' not found.`,
+                suggestion: 'Check the symbol name or use --to-uid for zero-ambiguity.',
+            };
+        }
+        if (toOutcome.kind === 'ambiguous') {
+            const { atLeast, showing, fields } = ambiguityReport(toOutcome, toOutcome.candidates.length);
+            return {
+                status: 'ambiguous',
+                role: 'to',
+                message: `Found ${atLeast}${toOutcome.total} symbols matching '${params.to}'${showing}. Disambiguate with --to-uid.`,
+                ...fields,
+                candidates: toOutcome.candidates,
+            };
+        }
+        const fromSym = fromOutcome.symbol;
+        const toSym = toOutcome.symbol;
+        if (fromSym.id === toSym.id) {
+            return {
+                status: 'ok',
+                from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+                to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+                hopCount: 0,
+                hops: [{ name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine }],
+                edges: [],
+            };
+        }
+        // Sanitize maxDepth at the real boundary: the MCP inputSchema's
+        // minimum/maximum is advisory only (callTool is reachable directly), so a
+        // caller can pass 0, a negative, NaN, or a non-integer. `??` does NOT
+        // recover 0/NaN, and Math.min has no lower bound — left unguarded, any of
+        // those makes the BFS loop run zero iterations and return a false no_path.
+        const DEFAULT_TRACE_DEPTH = 10;
+        const MAX_TRACE_DEPTH = 30;
+        const requestedDepth = Number.isInteger(params.maxDepth) && params.maxDepth > 0
+            ? params.maxDepth
+            : DEFAULT_TRACE_DEPTH;
+        const maxDepth = Math.min(requestedDepth, MAX_TRACE_DEPTH);
+        const includeTests = params.includeTests ?? false;
+        // Traversal vocabulary: CALLS for actual calls, HAS_METHOD so a class-rooted
+        // trace can descend into its methods. Not "calls only" — per-hop edge type is
+        // surfaced in edges[] so containment hops stay distinguishable.
+        const TRAVERSAL_EDGE_TYPES = ['CALLS', 'HAS_METHOD'];
+        // Bound the traversal so a high-fanout hub (a logger/util reached by many
+        // symbols) can't materialize an unbounded frontier. Per-level rows are
+        // capped and the total visited set is capped; either cap sets `truncated`
+        // so a resulting no_path is never reported as if the graph was exhausted.
+        const PER_NODE_FANOUT_CAP = 200;
+        const ABS_ROW_CAP = 5000;
+        const MAX_VISITED = 50000;
+        let truncated = false;
+        const visited = new Set([fromSym.id]);
+        let frontier = [fromSym.id];
+        const parent = new Map();
+        let found = false;
+        // The last node discovered at the deepest reached level — surfaced as
+        // `furthest` in the no_path response to hint where the chain breaks.
+        let lastReached = null;
+        let reachedDepth = 0;
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0 && !found; depth++) {
+            const nextFrontier = [];
+            // LadybugDB/Kuzu does not support a parameterized LIMIT, so the cap is
+            // interpolated (it is a derived integer, not user input).
+            //
+            // The ORDER BY below is required for two separate reasons (#2787). When a
+            // level overflows `rowCap`, an unordered LIMIT decided WHICH neighbours
+            // survived per process — so the same trace(from, to) could return a path
+            // on one run and `no_path` on the next. And even with no truncation, the
+            // `parent` map below is first-writer-wins, so among several equal-length
+            // shortest paths the reported hops/edges (and `lastReached`) followed raw
+            // row order.
+            const rowCap = Math.min(frontier.length * PER_NODE_FANOUT_CAP, ABS_ROW_CAP);
+            const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (n)-[r:CodeRelation]->(m)
+         WHERE n.id IN $frontierIds AND r.type IN $edgeTypes
+         RETURN n.id AS sourceId, m.id AS id, m.name AS name, labels(m)[0] AS type,
+                m.filePath AS filePath, m.startLine AS startLine,
+                r.type AS edgeType, r.confidence AS confidence
+         ORDER BY sourceId, id, edgeType
+         LIMIT ${rowCap}`, { frontierIds: frontier, edgeTypes: TRAVERSAL_EDGE_TYPES });
+            // A clipped level may have dropped a node that lies on the only shortest
+            // path, so any subsequent no_path is not authoritative.
+            if (rows.length >= rowCap)
+                truncated = true;
+            for (const row of rows) {
+                // Decode once. The `?? row[N]` fallback handles LadybugDB tuple-mode
+                // returns; the positional indices mirror the RETURN column order above.
+                const nodeId = (row.id ?? row[1]);
+                const sourceId = (row.sourceId ?? row[0]);
+                const name = (row.name ?? row[2]);
+                const filePath = (row.filePath ?? row[4]);
+                const startLine = (row.startLine ?? row[5]);
+                const edgeType = (row.edgeType ?? row[6]);
+                const storedConfidence = row.confidence ?? row[7];
+                const confidence = typeof storedConfidence === 'number' && storedConfidence > 0
+                    ? storedConfidence
+                    : confidenceForRelType(edgeType);
+                // Match the explicitly-requested target before the test-file filter.
+                // resolveSymbolCandidates does not exclude test-file symbols, so a
+                // target (or a required hop) that lives in a test file would otherwise
+                // be dropped by the includeTests guard below and produce a false
+                // no_path even when a direct edge exists.
+                if (nodeId === toSym.id) {
+                    parent.set(nodeId, { from: sourceId, name, filePath, startLine, edgeType, confidence });
+                    found = true;
+                    break;
+                }
+                // Skip non-target nodes that live in test files unless includeTests.
+                if (!includeTests && isTestFilePath(filePath))
+                    continue;
+                if (!visited.has(nodeId)) {
+                    visited.add(nodeId);
+                    parent.set(nodeId, { from: sourceId, name, filePath, startLine, edgeType, confidence });
+                    nextFrontier.push(nodeId);
+                    lastReached = { name, filePath, startLine };
+                    reachedDepth = depth;
+                }
+            }
+            frontier = nextFrontier;
+            if (visited.size >= MAX_VISITED) {
+                truncated = true;
+                break;
+            }
+        }
+        if (found) {
+            const path = [];
+            const edges = [];
+            let current = toSym.id;
+            while (current !== fromSym.id) {
+                const info = parent.get(current);
+                path.unshift({ name: info.name, filePath: info.filePath, startLine: info.startLine });
+                edges.unshift({ relType: info.edgeType, confidence: info.confidence });
+                current = info.from;
+            }
+            path.unshift({
+                name: fromSym.name,
+                filePath: fromSym.filePath,
+                startLine: fromSym.startLine,
+            });
+            return {
+                status: 'ok',
+                from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+                to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+                hopCount: edges.length,
+                hops: path,
+                edges,
+            };
+        }
+        return {
+            status: 'no_path',
+            from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+            to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+            furthest: lastReached ? { ...lastReached, depth: reachedDepth } : null,
+            ...(truncated ? { truncated: true } : {}),
+            suggestion: truncated
+                ? 'Search was truncated at a traversal cap before exhausting the graph — a path ' +
+                    'may still exist. Narrow the search (a lower --depth, or trace from a more ' +
+                    'specific symbol), or use cgraph context <symbol> to inspect connections.'
+                : 'No directed path found. The call chain likely breaks at dynamic dispatch, ' +
+                    'reflection, or an external API boundary. Try cgraph context <symbol> to see ' +
+                    "both symbols' connections, or check if an interface/abstraction bridges them.",
+        };
+    }
+    async impact(repo, params) {
+        try {
+            return await this._impactImpl(repo, params);
+        }
+        catch (err) {
+            // Return structured error instead of crashing (#321)
+            const message = (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed';
+            const suggestion = 'The graph query failed — try cgraph context <symbol> as a fallback';
+            const recoverySuggestion = (0, lbug_config_js_1.isWalCorruptionError)(err) ? lbug_config_js_1.WAL_RECOVERY_SUGGESTION : undefined;
+            return {
+                error: message,
+                target: { name: params.target },
+                direction: params.direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+                suggestion,
+                ...(recoverySuggestion ? { recoverySuggestion } : {}),
+            };
+        }
+    }
+    async _impactImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        const { target, direction } = params;
+        const maxDepth = params.maxDepth || 3;
+        // Map legacy relation type names before filtering (backward compat for OVERRIDES → METHOD_OVERRIDES)
+        const mappedRelTypes = params.relationTypes?.flatMap((t) => t === 'OVERRIDES' ? ['OVERRIDES', 'METHOD_OVERRIDES'] : [t]);
+        const hasExplicitRelationTypes = mappedRelTypes !== undefined && mappedRelTypes.length > 0;
+        const rawRelTypes = mappedRelTypes && mappedRelTypes.length > 0
+            ? mappedRelTypes.filter((t) => exports.VALID_RELATION_TYPES.has(t))
+            : [
+                'CALLS',
+                'IMPORTS',
+                'EXTENDS',
+                'IMPLEMENTS',
+                'USES',
+                'METHOD_OVERRIDES',
+                'OVERRIDES',
+                'METHOD_IMPLEMENTS',
+                // 跨服务调用边(spec §4):使 impact 默认遍历可跨 RCALLS/HTTP_CALLS
+                'RCALLS',
+                'HTTP_CALLS',
+            ];
+        const relationTypes = rawRelTypes.length > 0
+            ? rawRelTypes
+            : [
+                'CALLS',
+                'IMPORTS',
+                'EXTENDS',
+                'IMPLEMENTS',
+                'USES',
+                'METHOD_OVERRIDES',
+                'OVERRIDES',
+                'METHOD_IMPLEMENTS',
+                // 跨服务调用边(spec §4):使 impact 默认遍历可跨 RCALLS/HTTP_CALLS
+                'RCALLS',
+                'HTTP_CALLS',
+            ];
+        const includeTests = params.includeTests ?? false;
+        const minConfidence = params.minConfidence ?? 0;
+        // Resolve target via the shared symbol resolver. When the caller passes
+        // target_uid we skip the name lookup entirely (zero-ambiguity). Otherwise
+        // we rank candidates (#470) and either proceed with a confident single
+        // match, or return a structured ambiguous response instead of silently
+        // picking the wrong symbol.
+        //
+        // The resolver preserves the #480 Class/Constructor preference heuristic:
+        // when a Class and its Constructor share name + filePath, the Class is
+        // selected silently.
+        const outcome = await this.resolveSymbolCandidates(repo, { uid: params.target_uid, name: target }, { file_path: params.file_path, kind: params.kind });
+        if (outcome.kind === 'not_found') {
+            const missing = params.target_uid ?? target;
+            return {
+                error: `Target '${missing}' not found`,
+                target: { name: target },
+                direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+            };
+        }
+        if (outcome.kind === 'ambiguous') {
+            // Truncation cap for the ambiguous candidate probe list.
+            const AMBIGUOUS_MAX_CANDIDATES = 6;
+            // #2129 — a bare name that collides with several symbols must NOT report a
+            // bare `impactedCount: 0`. The real blast radius lives under whichever
+            // candidate the caller meant; a flat zero here is precisely the silent
+            // under-report the "run impact before editing" workflow exists to prevent
+            // (the dropped caller calls a *different* same-name node, so it never shows
+            // up against the one the resolver happened to pick). Run a bounded,
+            // summary-only BFS per candidate so each one's true count + risk is
+            // visible, and surface the maximum at the top level so the headline can
+            // never read as "safe to refactor". Candidates arrive sorted by score.
+            const probed = outcome.candidates.slice(0, AMBIGUOUS_MAX_CANDIDATES);
+            // `partialProbe` is intentionally a SECOND incompleteness flag, distinct
+            // from the traversal-interrupted `partial` flag used elsewhere: it means
+            // one or more per-candidate probes threw, so maxRisk / maxImpactedCount
+            // are lower bounds over the probes that succeeded (a failed candidate must
+            // not be masked by a benign sibling success).
+            let probeFailed = false;
+            const candidateSummaries = await Promise.all(probed.map(async (c) => {
+                const cType = c.type || '';
+                const cRelTypes = (cType === 'Class' || cType === 'Interface') &&
+                    !hasExplicitRelationTypes &&
+                    !relationTypes.includes('ACCESSES')
+                    ? [...relationTypes, 'ACCESSES']
+                    : relationTypes;
+                // #1858/#2129 review F8 — name the shape the probe summary is read
+                // through (`_runImpactBFS` returns `Promise<any>`, so this is the
+                // narrowing cast) so a future rename of those fields fails tsc instead
+                // of silently zeroing candidate counts.
+                let summary = null;
+                try {
+                    summary = await this._runImpactBFS(repo, { id: c.id, name: c.name, filePath: c.filePath }, cType, direction, {
+                        maxDepth,
+                        relationTypes: cRelTypes,
+                        includeTests,
+                        minConfidence,
+                        summaryOnly: true,
+                        skipEpistemic: true,
+                        skipEnrichment: true,
+                    });
+                }
+                catch (e) {
+                    probeFailed = true;
+                    logQueryError('impact:ambiguous-candidate', e);
+                }
+                return {
+                    uid: c.id,
+                    name: c.name,
+                    kind: c.type,
+                    filePath: c.filePath,
+                    line: (0, line_display_js_1.toDisplayLine)(c.startLine),
+                    score: Number(c.score.toFixed(2)),
+                    impactedCount: summary?.impactedCount ?? 0,
+                    risk: summary?.risk ?? 'UNKNOWN',
+                    direct: summary?.summary?.direct ?? 0,
+                };
+            }));
+            // Rank by blast radius so the most-impactful interpretation is first, and
+            // hoist the maximum count/risk to the top level so the response cannot be
+            // misread as "no impact".
+            candidateSummaries.sort((a, b) => b.impactedCount - a.impactedCount);
+            const maxImpactedCount = candidateSummaries.reduce((m, c) => Math.max(m, c.impactedCount), 0);
+            const RISK_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+            // If EVERY candidate probe failed (all 'UNKNOWN' — e.g. pool exhaustion
+            // under the fan-out), the worst real risk is genuinely unknown, not LOW.
+            // Reporting LOW here would re-introduce the false-safe signal. Only fall to
+            // the LOW seed when at least one candidate produced a real risk.
+            const anyKnownRisk = candidateSummaries.some((c) => RISK_ORDER.includes(c.risk));
+            const maxRisk = anyKnownRisk
+                ? candidateSummaries.reduce((worst, c) => (RISK_ORDER.indexOf(c.risk) > RISK_ORDER.indexOf(worst) ? c.risk : worst), 'LOW')
+                : 'UNKNOWN';
+            // `candidateSummaries` is `Promise.all` over `probed`, so the two lengths
+            // are the same; `probed` is the one the message and the flag agree on.
+            const { atLeast, showing, fields } = ambiguityReport(outcome, probed.length, true);
+            return {
+                status: 'ambiguous',
+                message: `Found ${atLeast}${outcome.total} symbols matching '${target}'` +
+                    showing +
+                    `. Blast radius differs per candidate (max ${maxImpactedCount} impacted at risk ${maxRisk}). ` +
+                    `Disambiguate with target_uid (or file_path/kind) for a single authoritative result.`,
+                target: { name: target },
+                direction,
+                // `totalCandidates` is the resolver's COUNT, not `candidates.length`:
+                // that array is truncated to AMBIGUOUS_MAX_CANDIDATES and the resolver
+                // window itself caps at CANDIDATE_WINDOW, so consumers (CLI formatter)
+                // need the COUNT to report "N of M" honestly (#2129 review F11; the CLI
+                // previously read the truncated array length, then the capped window
+                // length — both undercounts).
+                ...fields,
+                // `impactedCount` is `null` — UNDETERMINED, not zero — and `risk` stays
+                // UNKNOWN, because there is no single resolved symbol. #2129 hoisted
+                // `maxImpactedCount` / `maxRisk` here so a real caller could not hide
+                // behind the ambiguous zero, but the zero itself remained
+                // byte-identical to a genuine "nothing depends on this": a consumer
+                // testing `impactedCount === 0` still read a confident all-clear
+                // without ever looking at `candidates[]`. `null` cannot be mistaken for
+                // a measured zero, while `|| 0` consumers are unchanged (#2687).
+                impactedCount: null,
+                risk: 'UNKNOWN',
+                maxImpactedCount,
+                maxRisk,
+                ...(probeFailed ? { partialProbe: true } : {}),
+                candidates: candidateSummaries,
+            };
+        }
+        const sym = {
+            id: outcome.symbol.id,
+            name: outcome.symbol.name,
+            filePath: outcome.symbol.filePath,
+        };
+        const symType = outcome.resolvedLabel || outcome.symbol.type || '';
+        const effectiveRelationTypes = (symType === 'Class' || symType === 'Interface') &&
+            !hasExplicitRelationTypes &&
+            !relationTypes.includes('ACCESSES')
+            ? [...relationTypes, 'ACCESSES']
+            : relationTypes;
+        return this._runImpactBFS(repo, sym, symType, direction, {
+            maxDepth,
+            relationTypes: effectiveRelationTypes,
+            includeTests,
+            minConfidence,
+            limit: Number.isFinite(params.limit) ? params.limit : 100,
+            offset: Number.isFinite(params.offset) ? params.offset : 0,
+            summaryOnly: params.summaryOnly,
+        });
+    }
+    /**
+     * #1858 — epistemic lower-bound detection.
+     *
+     * impact()/context() traverse only edges materialized in the graph. When the
+     * queried symbol sits on an interface / abstract boundary, callers that bind
+     * to the interface via DI, a container, or dynamic dispatch — rather than
+     * naming the concrete symbol — are not traced. The reported count is then a
+     * lower bound, not an exact figure. Instead of returning a confident count
+     * that silently omits those callers, annotate the result with
+     * `epistemic: 'lower-bound'` plus a human-readable boundary note. A fully
+     * resolved leaf with no indirection stays `epistemic: 'exact'`.
+     *
+     * Aligns with the numeric confidence model rather than the long-deleted
+     * TIER_CONFIDENCE enum: the heritage/indirection edges this keys on
+     * (IMPLEMENTS / METHOD_IMPLEMENTS / EXTENDS) carry the 0.85
+     * `IMPACT_RELATION_CONFIDENCE` floor — "statically verifiable, but the
+     * concrete binding past it is not".
+     *
+     * Never throws: on query error it returns 'exact', so it can only add signal,
+     * never suppress a result.
+     */
+    async computeEpistemicBoundary(repo, symId, symType, symName) {
+        const HERITAGE_TYPES = exports.EPISTEMIC_HERITAGE_RELATION_TYPES;
+        const CONSUMER_TYPES = exports.EPISTEMIC_CONSUMER_RELATION_TYPES;
+        // #2744 — call sites dropped for want of a receiver type. Checked BEFORE
+        // the heritage probe below and reported even when that probe finds nothing:
+        // the two are independent reasons a count can be short, and this one is the
+        // reason #2708 was filed. A dropped site's callee is unknown, so the index
+        // records the member NAME invoked at the drop; a match on the queried
+        // symbol's name means at least one call to something of that name was lost.
+        const droppedBoundaries = await this.unresolvedReceiverBoundaries(repo, symName);
+        try {
+            // Discover the interface / abstract supertypes on the target's boundary.
+            // If the target is itself an interface, it is its own boundary node.
+            const boundary = new Map();
+            if (symType === 'Interface') {
+                boundary.set(symId, { name: symName || '', label: 'Interface' });
+            }
+            const ifaceRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (x)-[r:CodeRelation]->(iface)
+         WHERE x.id = $symId AND r.type IN $heritage
+         RETURN DISTINCT iface.id AS id, iface.name AS name, labels(iface)[0] AS label
+         ORDER BY id
+         LIMIT 25`, { symId, heritage: HERITAGE_TYPES }).catch(() => []);
+            for (const r of ifaceRows) {
+                const id = (r.id ?? r[0]);
+                if (id && !boundary.has(id)) {
+                    boundary.set(id, {
+                        name: (r.name ?? r[1] ?? ''),
+                        label: (r.label ?? r[2] ?? 'Interface'),
+                    });
+                }
+            }
+            if (boundary.size === 0)
+                return epistemicFrom(droppedBoundaries);
+            const ifaceIds = Array.from(boundary.keys());
+            // Count per interface id with scalar equality. A parameterized
+            // `iface.id IN $ids` combined with `COUNT(DISTINCT ...)` + implicit
+            // group-by returns no rows under the LadybugDB cypher subset, so query
+            // each boundary node individually (boundary is small — capped at 25).
+            const countByType = async (types) => {
+                const m = new Map();
+                await Promise.all(ifaceIds.map(async (ifaceId) => {
+                    const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `MATCH (other)-[r:CodeRelation]->(iface)
+               WHERE iface.id = $ifaceId AND r.type IN $types
+               RETURN COUNT(DISTINCT other.id) AS cnt`, { ifaceId, types }).catch(() => []);
+                    const cnt = rows.length > 0 ? Number(rows[0].cnt ?? rows[0][0] ?? 0) : 0;
+                    m.set(ifaceId, cnt);
+                }));
+                return m;
+            };
+            const [implCounts, consumerCounts] = await Promise.all([
+                countByType(HERITAGE_TYPES),
+                countByType(CONSUMER_TYPES),
+            ]);
+            const boundaries = [];
+            // Magnitude, not note count: see `EpistemicCauses.dispatchBoundary`. One
+            // note can describe an interface with 40 implementations and hundreds of
+            // interface-level consumers, so publishing `boundaries.length` would put
+            // `1` next to a `receiverTyping` of `12` and tell a consumer branching on
+            // the numbers that receiver typing dominates — the opposite of the truth.
+            let dispatchBoundarySymbols = 0;
+            for (const [id, info] of boundary) {
+                const impls = implCounts.get(id) ?? 0;
+                const consumers = consumerCounts.get(id) ?? 0;
+                // Flag only a genuine indirection risk: an interface that is actually
+                // consumed (callers bind to it) or that has multiple implementations
+                // (runtime dispatch is ambiguous). A concrete type implementing an
+                // interface nothing references is fully traced → stays exact.
+                if (consumers >= 1 || impls >= 2) {
+                    dispatchBoundarySymbols += impls + consumers;
+                    const label = (info.label || 'Interface').toLowerCase();
+                    const name = info.name || '(unnamed)';
+                    const article = /^[aeiou]/.test(label) ? 'an' : 'a';
+                    const parts = [];
+                    if (impls >= 1)
+                        parts.push(`${impls} ${impls === 1 ? 'implementation' : 'implementations'}`);
+                    if (consumers >= 1)
+                        parts.push(`${consumers} interface-level ${consumers === 1 ? 'consumer' : 'consumers'}`);
+                    boundaries.push(`${name} is ${article} ${label} with ${parts.join(' and ')}; callers that bind via the ${label} ` +
+                        `(e.g. a DI container or dynamic dispatch) are not traced to the concrete symbol — ` +
+                        `actual impact may be higher.`);
+                }
+            }
+            if (boundaries.length === 0)
+                return epistemicFrom(droppedBoundaries);
+            return {
+                epistemic: 'lower-bound',
+                boundaries: [...droppedBoundaries.notes, ...boundaries],
+                causes: {
+                    receiverTyping: droppedBoundaries.sites,
+                    dispatchBoundary: dispatchBoundarySymbols,
+                    externalBoundary: droppedBoundaries.external,
+                },
+            };
+        }
+        catch {
+            // Never let the heritage probe's failure suppress a drop we already know
+            // about — the whole point is that silence must not read as certainty.
+            return epistemicFrom(droppedBoundaries);
+        }
+    }
+    /**
+     * Boundary notes for call sites the analyzer dropped because it could not
+     * type their receiver, when the queried symbol's name is among them (#2744).
+     * Empty when the index records no drops for this name — including every
+     * index written before the summary existed, which is why the schema version
+     * was bumped rather than treating "absent" as "none".
+     */
+    async unresolvedReceiverBoundaries(repo, symName) {
+        if (symName.length === 0)
+            return { notes: [], sites: 0, external: 0 };
+        try {
+            const meta = await (0, repo_manager_js_1.loadMeta)(path_1.default.dirname(repo.lbugPath));
+            const summary = meta?.unresolvedReceiverMembers;
+            // Prototype-safe: see `lookupUnresolvedCallCount`. A bare `counts[symName]`
+            // returns a Function for `constructor`/`toString`/… and `NaN <= 0` is false,
+            // so the old guard let it through into user-facing text.
+            const sites = (0, unresolved_receivers_js_1.lookupUnresolvedCallCount)(summary, symName);
+            const external = (0, unresolved_receivers_js_1.lookupExternalCallCount)(summary, symName) ?? 0;
+            if (sites === undefined)
+                return { notes: [], sites: 0, external };
+            const notes = [
+                `${sites} call ${sites === 1 ? 'site' : 'sites'} invoking \`${symName}\` ${sites === 1 ? 'was' : 'were'} dropped at index time because the receiver's type could not be ` +
+                    `established (e.g. an unresolved constructor, factory or chained ` +
+                    `expression). Those callers are absent from this result — actual ` +
+                    `impact may be higher.`,
+            ];
+            return { notes, sites, external };
+        }
+        catch {
+            return { notes: [], sites: 0, external: 0 };
+        }
+    }
+    /**
+     * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
+     */
+    async _runImpactBFS(repo, sym, symType, direction, opts) {
+        const { maxDepth, relationTypes, includeTests, minConfidence } = opts;
+        const skipEnrichment = opts.skipEnrichment ?? false;
+        const hasExplicitLimit = typeof opts.limit === 'number' && Number.isFinite(opts.limit);
+        const paginationLimit = hasExplicitLimit
+            ? Math.max(1, Math.min(Math.trunc(opts.limit), 10000))
+            : Infinity;
+        const rawOffset = typeof opts.offset === 'number' && Number.isFinite(opts.offset) ? opts.offset : 0;
+        const paginationOffset = Math.max(0, Math.trunc(rawOffset));
+        const summaryOnly = opts.summaryOnly ?? false;
+        // Bind the BFS frontier query's filters as parameters (#1907 review F5):
+        // node ids and relation types as bound lists, the confidence floor as a
+        // bound number — no string interpolation reaches the query text. Preserve
+        // the original "no confidence clause when minConfidence <= 0" behavior: an
+        // unconditional `>= 0` would wrongly exclude NULL-confidence edges that the
+        // unfiltered query includes.
+        const safeMinConfidence = Number.isFinite(minConfidence) ? minConfidence : 0;
+        const confidenceFilter = safeMinConfidence > 0 ? ' AND r.confidence >= $minConfidence' : '';
+        const symId = sym.id || sym[0];
+        // #1858 — kick off the epistemic boundary probe concurrently with the BFS.
+        // It depends only on symId/symType/symName (all known now) and touches no
+        // shared state, so its extra round-trip overlaps the traversal instead of
+        // adding to the serial path. `skipEpistemic` (ambiguous #2129 candidate
+        // probes, group fan-out) resolves to no field, preserving prior behavior.
+        // #1858/#2129 review F8 — the skip case adds no field, so `epistemic` is
+        // optional here (the union's `{}` subtype). computeEpistemicBoundary's own
+        // return keeps `epistemic` REQUIRED — only this promise widens to the skip
+        // subtype.
+        // `causes` is part of the annotation, not just of the runtime value: the
+        // spread below is what publishes these fields, and a narrower annotation
+        // erases `causes` at the type level while still shipping it at runtime —
+        // so every consumer would be reading a field the compiler says is absent.
+        const epistemicPromise = opts.skipEpistemic
+            ? Promise.resolve({})
+            : this.computeEpistemicBoundary(repo, symId, symType, (sym.name || sym[1]));
+        const beanMetadataPromise = opts.skipEpistemic || summaryOnly
+            ? Promise.resolve(undefined)
+            : (0, bean_metadata_js_1.queryClassBeanMetadata)(repo.lbugPath, symId, symType);
+        const aopMetadataPromise = opts.skipEpistemic || summaryOnly
+            ? Promise.resolve(undefined)
+            : (0, aop_metadata_js_1.querySpringAopMetadata)(repo.lbugPath, symId, symType);
+        const impacted = [];
+        const visited = new Set([symId]);
+        let frontier = [symId];
+        let traversalComplete = true;
+        // Fix #480: For Java (and other JVM) Class/Interface nodes, CALLS edges
+        // point to Constructor nodes and IMPORTS edges point to File nodes — not
+        // the Class/Interface itself. Seed the frontier with the Constructor(s)
+        // and owning File so the BFS traversal finds those edges naturally.
+        // The owning File is kept only as an internal seed (frontier/visited) and
+        // is NOT added to impacted — it is the definition container, not an
+        // upstream dependent. The BFS will discover IMPORTS edges on it naturally.
+        if (symType === 'Class' || symType === 'Interface') {
+            try {
+                // Run both seed queries in parallel — they are independent.
+                const [ctorRows, fileRows] = await Promise.all([
+                    (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (n)-[hm:CodeRelation]->(c:Constructor)
+            WHERE n.id = $symId AND hm.type = 'HAS_METHOD'
+            RETURN c.id AS id, c.name AS name, labels(c)[0] AS type, c.filePath AS filePath
+          `, { symId }),
+                    // Restrict to DEFINES edges only — other File->Class edge types (if
+                    // any) should not be treated as the owning file relationship.
+                    (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (f:File)-[rel:CodeRelation]->(n)
+            WHERE n.id = $symId AND rel.type = 'DEFINES'
+            RETURN f.id AS id, f.name AS name, labels(f)[0] AS type, f.filePath AS filePath
+          `, { symId }),
+                ]);
+                for (const r of ctorRows) {
+                    const rid = r.id || r[0];
+                    if (rid && !visited.has(rid)) {
+                        visited.add(rid);
+                        frontier.push(rid);
+                    }
+                }
+                for (const r of fileRows) {
+                    const rid = r.id || r[0];
+                    if (rid && !visited.has(rid)) {
+                        visited.add(rid);
+                        frontier.push(rid);
+                    }
+                }
+                const typedPropertyRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+          MATCH (p:\`Property\`)
+          WHERE p.declaredType = $name
+             OR p.declaredType STARTS WITH $genericPrefix
+             OR p.declaredType CONTAINS $genericArg
+          RETURN p.id AS id, p.name AS name, labels(p)[0] AS type, p.filePath AS filePath
+        `, {
+                    name: sym.name,
+                    genericPrefix: `${sym.name}<`,
+                    genericArg: `<${sym.name}>`,
+                });
+                for (const r of typedPropertyRows) {
+                    const rid = r.id || r[0];
+                    if (rid && !visited.has(rid)) {
+                        visited.add(rid);
+                        frontier.push(rid);
+                    }
+                }
+            }
+            catch (e) {
+                logQueryError('impact:class-node-expansion', e);
+            }
+        }
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+            const nextFrontier = [];
+            // Batch frontier nodes into a single Cypher query per depth level.
+            // ids/types/confidence are bound parameters (see above) — no interpolation.
+            //
+            // Deliberately NO `ORDER BY` (#2787). Every other ordered query in this
+            // file pairs its key with a small `LIMIT`, so the engine answers it from a
+            // bounded top-k heap and the ordering is nearly free. This one had no such
+            // escape: the engine had to materialize and fully sort EVERY neighbour edge
+            // of the whole frontier — tens of thousands of rows at depth 2 for a hub
+            // symbol — on a four-key comparator led by a long
+            // `Label:filePath:qualifiedName` string, dragging the wide `name`/
+            // `filePath` columns through the sort, once per depth level, on the tool
+            // that runs before every symbol edit.
+            //
+            // The ordering only ever served three POSITIONAL consumers of `impacted`:
+            // the relationType/confidence stamped on a node reached by more than one
+            // edge (the first row won); the process/module enrichment, which covers
+            // only `impacted.slice(0, MAX_CHUNKS * CHUNK_SIZE)` and feeds the risk
+            // thresholds; and byDepth pagination, which slices without re-sorting. All
+            // three need strictly less than a total sort of edges, so the ordering now
+            // lives in JS below, where the guarantee is STRONGER as well as cheaper:
+            // an engine's collation and sort stability are not ours to specify or
+            // version-pin, whereas `compareCodeUnits` is exactly UTF-16 code-unit
+            // order and `impactEdgeConfidenceRank` pins where a NULL confidence lands.
+            // Reproduced there, at O(E) plus a sort of NODES rather than of edges:
+            //   * per reached id, an argmax under `relType ASC, confidence DESC,
+            //     sourceId ASC` — what "first row wins" meant once the key led with
+            //     `id` — via `compareImpactEdgeStrength`, and
+            //   * `impacted` appended id-ascending over the distinct newly-visited
+            //     nodes, via `compareImpactFrontierEdges`.
+            //
+            // `confidence DESC` is part of the key, not decoration (#2787 review F2):
+            // (id, relType) is NOT unique — 2181 of ~10020 groups on this repo's index
+            // carry more than one distinct confidence, and 0.7 vs 0.85 straddles the
+            // `< 0.8 = fuzzy` boundary the tool description publishes. Taking the
+            // strongest edge makes the stamped pair fully determined by the key AND
+            // retains the strongest evidence, the safer default for a blast-radius
+            // tool. `sourceId` closes the order for edges that tie on both.
+            const query = direction === 'upstream'
+                ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN $frontierIds AND r.type IN $relTypes${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, labels(caller)[0] AS type, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
+                : `MATCH (n)-[r:CodeRelation]->(callee) WHERE n.id IN $frontierIds AND r.type IN $relTypes${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, labels(callee)[0] AS type, callee.filePath AS filePath, r.type AS relType, r.confidence AS confidence`;
+            try {
+                const related = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, query, {
+                    frontierIds: frontier,
+                    relTypes: relationTypes,
+                    ...(safeMinConfidence > 0 ? { minConfidence: safeMinConfidence } : {}),
+                });
+                const edges = related.map((rel) => ({
+                    id: rel.id || rel[1],
+                    name: rel.name || rel[2],
+                    type: rel.type || rel[3],
+                    filePath: rel.filePath || rel[4] || '',
+                    relType: rel.relType || rel[5],
+                    confidence: rel.confidence ?? rel[6],
+                    sourceId: String(rel.sourceId ?? rel[0] ?? ''),
+                }));
+                // Argmax edge per newly-reached node, under the key the DB used to
+                // carry. Rebuilt per depth level, exactly like `nextFrontier`.
+                const bestEdgeByNode = new Map();
+                for (const edge of edges) {
+                    if (!includeTests && isTestFilePath(edge.filePath))
+                        continue;
+                    // Nodes seeded or reached at an EARLIER depth contribute no new
+                    // `impacted` entry. `visited` no longer grows inside this pass — it
+                    // used to double as the "first row wins" argmax, a job
+                    // `bestEdgeByNode` now does explicitly — so the guard reads the same
+                    // set for every edge of the level, which is what it always meant.
+                    if (visited.has(edge.id))
+                        continue;
+                    const incumbent = bestEdgeByNode.get(edge.id);
+                    if (incumbent === undefined || compareImpactEdgeStrength(edge, incumbent) < 0) {
+                        bestEdgeByNode.set(edge.id, edge);
+                    }
+                }
+                for (const edge of [...bestEdgeByNode.values()].sort(compareImpactFrontierEdges)) {
+                    visited.add(edge.id);
+                    nextFrontier.push(edge.id);
+                    const storedConfidence = edge.confidence;
+                    const relationType = edge.relType;
+                    // Prefer the stored confidence from the graph (set at analysis time);
+                    // fall back to the per-type floor for edges without a stored value.
+                    const effectiveConfidence = typeof storedConfidence === 'number' && storedConfidence > 0
+                        ? storedConfidence
+                        : confidenceForRelType(relationType);
+                    impacted.push({
+                        depth,
+                        id: edge.id,
+                        name: edge.name,
+                        type: edge.type,
+                        filePath: edge.filePath,
+                        relationType,
+                        confidence: effectiveConfidence,
+                    });
+                }
+            }
+            catch (e) {
+                logQueryError('impact:depth-traversal', e);
+                // Break out of depth loop on query failure but return partial results
+                // collected so far, rather than silently swallowing the error (#321)
+                traversalComplete = false;
+                break;
+            }
+            frontier = nextFrontier;
+        }
+        const grouped = {};
+        for (const item of impacted) {
+            if (!grouped[item.depth])
+                grouped[item.depth] = [];
+            grouped[item.depth].push(item);
+        }
+        // ── Enrichment: affected processes, modules, risk ──────────────
+        const directCount = (grouped[1] || []).length;
+        let affectedProcesses = [];
+        let affectedModules = [];
+        // Per-symbol process membership: maps impacted symbol id -> list of processes
+        // it participates in. Populated by a second chunked Cypher pass below when
+        // any process is affected at all. Surfaced as `processes: [...]` on each
+        // byDepth item so consumers can tell which caller belongs to which cron/
+        // webhook/route without a follow-up query.
+        const perSymbolProcesses = new Map();
+        // Chunking bounds for batched DB round-trips. Declared at function scope so
+        // both the in-block enrichment passes and the post-pagination per-symbol
+        // process enrichment can reference them.
+        const CHUNK_SIZE = 100;
+        // Max number of chunks to process to avoid unbounded DB round-trips.
+        // Configurable via env IMPACT_MAX_CHUNKS, default 10 => max items = 1000
+        const MAX_CHUNKS = parseInt(process.env.IMPACT_MAX_CHUNKS || '10', 10);
+        // `skipEnrichment` (ambiguous #2129 per-candidate probes) bypasses the
+        // process/module aggregation passes entirely — those probes need only the
+        // count + a count-based risk, so paying the bounded-but-real enrichment cost
+        // ~6× per ambiguous call is wasted. risk then derives from directCount /
+        // total only (processCount/moduleCount stay 0), an acceptable approximation
+        // for a disambiguation aid.
+        if (impacted.length > 0 && !skipEnrichment) {
+            // ── Process enrichment: batched chunking (bounded by MAX_CHUNKS) ─
+            // Uses merged Cypher query (WITH + OPTIONAL MATCH) to fetch
+            // process + entry point info in 1 round-trip per chunk. Converted to
+            // parameterized queries to avoid manual string escaping and long query strings.
+            const entryPointMap = new Map();
+            // Map process id -> entryPointId to allow fixing missing minStep values later
+            const processToEntryPoint = new Map();
+            // Collect process ids where MIN(r.step) returned null so we can retry in batch
+            const processesMissingMinStep = new Set();
+            let chunksProcessed = 0;
+            for (let i = 0; i < impacted.length && chunksProcessed < MAX_CHUNKS; i += CHUNK_SIZE, chunksProcessed++) {
+                const chunk = impacted.slice(i, i + CHUNK_SIZE);
+                const ids = chunk.map((item) => String(item.id ?? ''));
+                try {
+                    // Use parameterized list to avoid building long query strings
+                    const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+            WHERE s.id IN $ids
+            WITH p, COUNT(DISTINCT s.id) AS hits, MIN(r.step) AS minStep
+            OPTIONAL MATCH (ep {id: p.entryPointId})
+            RETURN p.id AS pId, p.heuristicLabel AS name, p.processType AS processType,
+                   p.entryPointId AS entryPointId, hits, minStep, p.stepCount AS stepCount,
+                   ep.name AS epName, labels(ep)[0] AS epType, ep.filePath AS epFilePath
+            ORDER BY pId
+          `, { ids }).catch(() => []);
+                    for (const row of rows) {
+                        const pId = row.pId ?? row[0];
+                        const epId = row.entryPointId ?? row[3] ?? row.pId ?? row[0];
+                        // Track mapping from process -> entryPoint so we can backfill missing minStep
+                        if (pId)
+                            processToEntryPoint.set(String(pId), String(epId));
+                        // Normalize epName: prefer epName, fall back to other columns, and
+                        // ensure we don't keep an empty string (labels(...) can return "").
+                        const epNameRaw = row.epName ?? row[7] ?? row.name ?? row[1] ?? 'unknown';
+                        const epName = typeof epNameRaw === 'string' && epNameRaw.trim().length > 0
+                            ? epNameRaw.trim()
+                            : 'unknown';
+                        // Normalize epType: labels(ep)[0] can return an empty string in
+                        // some DBs (LadybugDB). Using nullish coalescing (??) preserves
+                        // empty strings, which results in empty `type` values being
+                        // propagated. Treat empty-string labels as missing and fall back
+                        // to the next candidate or a sensible default.
+                        const epTypeRaw = row.epType ?? row[8] ?? '';
+                        const epType = typeof epTypeRaw === 'string' && epTypeRaw.trim().length > 0
+                            ? epTypeRaw.trim()
+                            : 'Function';
+                        const epFilePath = row.epFilePath ?? row[9] ?? '';
+                        const hits = row.hits ?? row[4] ?? 0;
+                        const minStep = row.minStep ?? row[5];
+                        // If the DB returned null for minStep, note the process id so we
+                        // can run a follow-up query using a different aggregation strategy.
+                        if (minStep === null || minStep === undefined) {
+                            if (pId)
+                                processesMissingMinStep.add(String(pId));
+                        }
+                        if (!entryPointMap.has(epId)) {
+                            entryPointMap.set(epId, {
+                                name: epName,
+                                type: epType,
+                                filePath: epFilePath,
+                                affected_process_count: 0,
+                                total_hits: 0,
+                                earliest_broken_step: Infinity,
+                            });
+                        }
+                        const ep = entryPointMap.get(epId);
+                        ep.affected_process_count += 1;
+                        ep.total_hits += hits;
+                        ep.earliest_broken_step = Math.min(ep.earliest_broken_step, minStep ?? Infinity);
+                    }
+                }
+                catch (e) {
+                    logQueryError('impact:process-chunk', e);
+                }
+            }
+            // If some processes returned null minStep, try a batched follow-up query
+            // using the full impacted id set. This handles older indexes or DBs
+            // where MIN(r.step) can come back null even when step properties exist.
+            if (processesMissingMinStep.size > 0) {
+                try {
+                    const pIds = Array.from(processesMissingMinStep);
+                    const allImpactedIds = impacted.map((it) => String(it.id ?? ''));
+                    const missingRows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+            WHERE p.id IN $pIds AND s.id IN $ids
+            RETURN p.id AS pid, MIN(r.step) AS minStep
+          `, { pIds, ids: allImpactedIds }).catch(() => []);
+                    for (const mr of missingRows) {
+                        const pid = mr.pid ?? mr[0];
+                        const minStep = mr.minStep ?? mr[1];
+                        const epId = processToEntryPoint.get(String(pid));
+                        if (!epId)
+                            continue;
+                        const ep = entryPointMap.get(epId);
+                        if (!ep)
+                            continue;
+                        if (typeof minStep === 'number') {
+                            ep.earliest_broken_step = Math.min(ep.earliest_broken_step, minStep);
+                        }
+                    }
+                }
+                catch (e) {
+                    logQueryError('impact:process-chunk-backfill', e);
+                }
+            }
+            // If we capped chunks, mark traversal incomplete so caller knows results are partial
+            if (chunksProcessed * CHUNK_SIZE < impacted.length) {
+                traversalComplete = false;
+            }
+            // (total_hits, filePath, name) is NOT unique across distinct entry points —
+            // two of them collide on all three in this repo alone (`step`, same file,
+            // cgraph-web/src/hooks/useSigma.ts) and equal `total_hits` is the norm —
+            // so ties fell through to `Map` insertion order, i.e. raw row order (#2787
+            // review F6). Sort the ENTRIES so the entry-point id (the map key) can close
+            // the order, then project: the id stays out of the response payload.
+            affectedProcesses = Array.from(entryPointMap.entries())
+                .sort(([aId, a], [bId, b]) => b.total_hits - a.total_hits ||
+                (0, utils_js_1.compareCodeUnits)(a.filePath, b.filePath) ||
+                (0, utils_js_1.compareCodeUnits)(a.name, b.name) ||
+                (0, utils_js_1.compareCodeUnits)(aId, bId))
+                .map(([, ep]) => ({
+                ...ep,
+                earliest_broken_step: ep.earliest_broken_step === Infinity ? null : ep.earliest_broken_step,
+            }));
+            // Per-symbol process membership is populated post-pagination (see below)
+            // so it covers exactly the symbols returned in byDepth, not a pre-capped
+            // flat slice that could miss depth-2+ symbols when depth-1 is large.
+            // ── Module enrichment: use same cap as process enrichment and parameterized queries
+            const maxItems = Math.min(impacted.length, MAX_CHUNKS * CHUNK_SIZE);
+            const cappedImpacted = impacted.slice(0, maxItems);
+            const allIdsArr = cappedImpacted.map((i) => String(i.id ?? ''));
+            const d1Items = (grouped[1] || []).slice(0, maxItems);
+            const d1IdsArr = d1Items.map((i) => String(i.id ?? ''));
+            // Chunked module enrichment: run the MEMBER_OF queries in chunks
+            // to avoid large single queries or concurrent Kuzu calls that can
+            // crash (SIGSEGV) on arm64 macOS; behavior preserves existing maxItems cap and returns equivalent aggregated results.
+            const moduleHitsMap = new Map();
+            const directModuleSet = new Set();
+            // Helper to run a single module chunk and accumulate hits by name
+            const runModuleChunk = async (idsChunk) => {
+                if (!idsChunk || idsChunk.length === 0)
+                    return;
+                try {
+                    const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+            WHERE s.id IN $ids
+            RETURN c.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits
+            ORDER BY hits DESC, name
+            LIMIT 20
+          `, { ids: idsChunk }).catch(() => []);
+                    for (const r of rows) {
+                        const name = r.name ?? r[0] ?? null;
+                        const hits = (r.hits ?? r[1]) || 0;
+                        if (!name)
+                            continue;
+                        moduleHitsMap.set(name, (moduleHitsMap.get(name) || 0) + hits);
+                    }
+                }
+                catch (e) {
+                    logQueryError('impact:module-chunk', e);
+                }
+            };
+            // Run module query chunks sequentially (safe on arm64 macOS)
+            for (let i = 0; i < allIdsArr.length; i += CHUNK_SIZE) {
+                const chunkIds = allIdsArr.slice(i, i + CHUNK_SIZE);
+                await runModuleChunk(chunkIds);
+            }
+            // Run direct module query similarly (distinct heuristic labels for depth-1 items)
+            const runDirectModuleChunk = async (idsChunk) => {
+                if (!idsChunk || idsChunk.length === 0)
+                    return;
+                try {
+                    const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+            WHERE s.id IN $ids
+            RETURN DISTINCT c.heuristicLabel AS name
+          `, { ids: idsChunk }).catch(() => []);
+                    for (const r of rows) {
+                        const name = r.name ?? r[0] ?? null;
+                        if (name)
+                            directModuleSet.add(name);
+                    }
+                }
+                catch (e) {
+                    logQueryError('impact:direct-module-chunk', e);
+                }
+            };
+            for (let i = 0; i < d1IdsArr.length; i += CHUNK_SIZE) {
+                const chunkIds = d1IdsArr.slice(i, i + CHUNK_SIZE);
+                await runDirectModuleChunk(chunkIds);
+            }
+            // Build final moduleRows array from aggregated hits map, sorted & limited
+            const moduleRows = Array.from(moduleHitsMap.entries())
+                .map(([name, hits]) => ({ name, hits }))
+                .sort((a, b) => b.hits - a.hits || (0, utils_js_1.compareCodeUnits)(String(a.name), String(b.name)))
+                .slice(0, 20);
+            const directModuleRows = Array.from(directModuleSet).map((name) => ({ name }));
+            // Build affectedModules in the same shape as original implementation
+            const directModuleNameSet = new Set(directModuleRows.map((r) => r.name || r[0]));
+            affectedModules = moduleRows.map((r) => {
+                const name = r.name ?? r[0];
+                const hits = r.hits ?? r[1] ?? 0;
+                return {
+                    name,
+                    hits,
+                    impact: directModuleNameSet.has(name) ? 'direct' : 'indirect',
+                };
+            });
+        }
+        // Risk scoring
+        const processCount = affectedProcesses.length;
+        const moduleCount = affectedModules.length;
+        let risk = 'LOW';
+        if (directCount >= 30 || processCount >= 5 || moduleCount >= 5 || impacted.length >= 200) {
+            risk = 'CRITICAL';
+        }
+        else if (directCount >= 15 ||
+            processCount >= 3 ||
+            moduleCount >= 3 ||
+            impacted.length >= 100) {
+            risk = 'HIGH';
+        }
+        else if (directCount >= 5 || impacted.length >= 30) {
+            risk = 'MEDIUM';
+        }
+        // Build per-depth counts (always included, even in summaryOnly mode)
+        const byDepthCounts = {};
+        for (const [depth, items] of Object.entries(grouped)) {
+            byDepthCounts[Number(depth)] = items.length;
+        }
+        // #1858 — await the epistemic boundary probe kicked off alongside the BFS
+        // above. Additive: leaves impactedCount and every existing field untouched.
+        const [epistemic, beanMetadata, aopMetadata] = await Promise.all([
+            epistemicPromise,
+            beanMetadataPromise,
+            aopMetadataPromise,
+        ]);
+        const base = {
+            target: {
+                id: symId,
+                name: sym.name || sym[1],
+                type: symType,
+                filePath: sym.filePath || sym[2],
+                ...(beanMetadata ? { bean: beanMetadata } : {}),
+                ...(aopMetadata ? { aop: aopMetadata } : {}),
+            },
+            direction,
+            impactedCount: impacted.length,
+            risk,
+            ...epistemic,
+            ...(!traversalComplete && { partial: true }),
+            summary: {
+                direct: directCount,
+                processes_affected: processCount,
+                modules_affected: moduleCount,
+            },
+            byDepthCounts,
+            affected_processes: affectedProcesses,
+            affected_modules: affectedModules,
+        };
+        if (summaryOnly) {
+            return base;
+        }
+        // Apply limit/offset pagination per depth level.
+        const paginatedGrouped = {};
+        let anyTruncated = false;
+        for (const [depth, items] of Object.entries(grouped)) {
+            const total = items.length;
+            const sliced = items.slice(paginationOffset, paginationOffset + paginationLimit);
+            paginatedGrouped[Number(depth)] = sliced;
+            if (paginationOffset > 0 || paginationOffset + paginationLimit < total) {
+                anyTruncated = true;
+            }
+        }
+        // ── Per-symbol process membership enrichment (post-pagination) ───────
+        // Runs after paginatedGrouped is built so we enrich only the IDs that
+        // actually appear in the response. This eliminates the false-empty
+        // processes:[] case where a depth-2+ symbol's flat position in `impacted`
+        // exceeded MAX_CHUNKS*CHUNK_SIZE even though it is returned by byDepth.
+        // Also uses DISTINCT + MIN(r.step) per (symbol, process) pair to avoid
+        // duplicate entries when a symbol has multiple STEP_IN_PROCESS edges.
+        let perSymbolEnrichmentCapped = false;
+        if (affectedProcesses.length > 0) {
+            // Collect unique IDs from the paginated result in one pass.
+            const pageIds = new Set();
+            for (const items of Object.values(paginatedGrouped)) {
+                for (const it of items) {
+                    const id = String(it.id ?? '');
+                    if (id)
+                        pageIds.add(id);
+                }
+            }
+            // Bound the enrichment to the same ceiling as the aggregation pass
+            // (MAX_CHUNKS * CHUNK_SIZE) so a large paginated page cannot trigger
+            // unbounded DB round-trips (DoD 2.6). When capped, mark the result
+            // partial so callers know some returned symbols may carry an empty
+            // processes:[] that is a cap artifact, not a true absence.
+            const maxPageIds = MAX_CHUNKS * CHUNK_SIZE;
+            let pageIdArr = Array.from(pageIds);
+            if (pageIdArr.length > maxPageIds) {
+                pageIdArr = pageIdArr.slice(0, maxPageIds);
+                perSymbolEnrichmentCapped = true;
+            }
+            for (let i = 0; i < pageIdArr.length; i += CHUNK_SIZE) {
+                const chunkIds = pageIdArr.slice(i, i + CHUNK_SIZE);
+                try {
+                    const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+            MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+            WHERE s.id IN $ids
+            RETURN s.id AS sid, p.id AS pid, p.heuristicLabel AS pName,
+                   p.processType AS pType, MIN(r.step) AS step
+          `, { ids: chunkIds }).catch(() => []);
+                    for (const row of rows) {
+                        const sid = row.sid ?? row[0];
+                        if (!sid)
+                            continue;
+                        const procEntry = {
+                            id: String(row.pid ?? row[1] ?? ''),
+                            label: String(row.pName ?? row[2] ?? ''),
+                            processType: String(row.pType ?? row[3] ?? ''),
+                            step: Number(row.step ?? row[4] ?? -1),
+                        };
+                        const list = perSymbolProcesses.get(String(sid));
+                        if (list)
+                            list.push(procEntry);
+                        else
+                            perSymbolProcesses.set(String(sid), [procEntry]);
+                    }
+                }
+                catch (e) {
+                    logQueryError('impact:per-symbol-process-chunk', e);
+                }
+            }
+        }
+        // Attach processes field to each paginated item.
+        for (const items of Object.values(paginatedGrouped)) {
+            for (const it of items) {
+                it.processes = perSymbolProcesses.get(String(it.id)) ?? [];
+            }
+        }
+        return {
+            ...base,
+            // Surface partial if the per-symbol enrichment was capped, even when the
+            // BFS traversal itself completed — some returned symbols may carry an
+            // empty processes:[] that is a cap artifact rather than a true absence.
+            ...(perSymbolEnrichmentCapped && { partial: true }),
+            ...(anyTruncated && {
+                pagination: {
+                    ...(Number.isFinite(paginationLimit) && { limit: paginationLimit }),
+                    offset: paginationOffset,
+                    truncated: true,
+                },
+            }),
+            byDepth: paginatedGrouped,
+        };
+    }
+    /**
+     * Fetch Route nodes with their consumers in a single query.
+     * Shared by routeMap and shapeCheck to avoid N+1 query patterns.
+     */
+    async fetchRoutesWithConsumers(repoId, routeFilter, params) {
+        const rows = await (0, pool_adapter_js_1.executeParameterized)(repoId, `
+      MATCH (n:Route)
+      WHERE n.id STARTS WITH 'Route:' ${routeFilter}
+      OPTIONAL MATCH (consumer)-[r:CodeRelation]->(n)
+      WHERE r.type = 'FETCHES'
+      RETURN n.id AS routeId, n.name AS routeName, n.filePath AS handlerFile,
+             n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware,
+             consumer.name AS consumerName, consumer.filePath AS consumerFile,
+             r.reason AS fetchReason, n.method AS method
+    `, params);
+        // Strip wrapping quotes from DB array elements — CSV COPY stores ['key'] which
+        // LadybugDB may return as "'key'" rather than "key"
+        const stripQuotes = (keys) => keys ? keys.map((k) => k.replace(/^['"]|['"]$/g, '')) : null;
+        const routeMap = new Map();
+        for (const row of rows) {
+            const id = row.routeId ?? row[0];
+            const name = row.routeName ?? row[1];
+            const filePath = row.handlerFile ?? row[2];
+            const responseKeys = stripQuotes(row.responseKeys ?? row[3] ?? null);
+            const errorKeys = stripQuotes(row.errorKeys ?? row[4] ?? null);
+            const middleware = stripQuotes(row.middleware ?? row[5] ?? null);
+            const consumerName = row.consumerName ?? row[6];
+            const consumerFile = row.consumerFile ?? row[7];
+            const fetchReason = row.fetchReason ?? row[8] ?? null;
+            // Verb is the literal '*' for method-agnostic routes (Django function
+            // views) and absent (null) for method-less routes (filesystem, Laravel
+            // resource). Appended last in RETURN so positional fallbacks for the
+            // consumer/reason columns above stay stable.
+            const method = row.method ?? row[9] ?? null;
+            if (!routeMap.has(id)) {
+                routeMap.set(id, {
+                    id,
+                    name,
+                    method,
+                    filePath,
+                    responseKeys,
+                    errorKeys,
+                    middleware,
+                    consumers: [],
+                });
+            }
+            if (consumerName && consumerFile) {
+                // Parse accessed keys from reason field: "fetch-url-match|keys:data,pagination|fetches:3"
+                let accessedKeys;
+                let fetchCount;
+                if (fetchReason) {
+                    const keysMatch = fetchReason.match(/\|keys:([^|]+)/);
+                    if (keysMatch) {
+                        accessedKeys = keysMatch[1].split(',').filter((k) => k.length > 0);
+                    }
+                    const fetchesMatch = fetchReason.match(/\|fetches:(\d+)/);
+                    if (fetchesMatch) {
+                        fetchCount = parseInt(fetchesMatch[1], 10);
+                    }
+                }
+                routeMap.get(id).consumers.push({
+                    name: consumerName,
+                    filePath: consumerFile,
+                    ...(accessedKeys ? { accessedKeys } : {}),
+                    ...(fetchCount && fetchCount > 1 ? { fetchCount } : {}),
+                });
+            }
+        }
+        return [...routeMap.values()];
+    }
+    /**
+     * Batch-fetch execution flows linked to a set of Route or Tool nodes.
+     * Single query instead of N+1.
+     */
+    async fetchLinkedFlowsBatch(repoId, nodeIds) {
+        const result = new Map();
+        if (nodeIds.length === 0)
+            return result;
+        try {
+            // Use list_contains to filter at DB level instead of fetching all and filtering in memory
+            const rows = await (0, pool_adapter_js_1.executeParameterized)(repoId, `
+        MATCH (source)-[r:CodeRelation]->(proc:Process)
+        WHERE r.type = 'ENTRY_POINT_OF'
+          AND list_contains($nodeIds, source.id)
+        RETURN source.id AS sourceId, proc.label AS name
+      `, { nodeIds });
+            for (const row of rows) {
+                const sourceId = row.sourceId ?? row[0];
+                const name = row.name ?? row[1];
+                if (!name)
+                    continue;
+                let list = result.get(sourceId);
+                if (!list) {
+                    list = [];
+                    result.set(sourceId, list);
+                }
+                list.push(name);
+            }
+        }
+        catch {
+            /* no ENTRY_POINT_OF edges yet */
+        }
+        return result;
+    }
+    async routeMap(repo, params) {
+        await this.ensureInitialized(repo);
+        const routeFilter = params.route ? `AND n.name CONTAINS $route` : '';
+        const queryParams = params.route ? { route: params.route } : {};
+        const routes = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
+        if (routes.length === 0) {
+            return {
+                routes: [],
+                total: 0,
+                message: params.route
+                    ? `No routes matching "${params.route}"`
+                    : 'No routes found in this project.',
+            };
+        }
+        const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, routes.map((r) => r.id));
+        return {
+            routes: routes.map((r) => ({
+                route: r.name,
+                method: r.method,
+                handler: r.filePath,
+                middleware: r.middleware || [],
+                consumers: r.consumers,
+                flows: flowMap.get(r.id) || [],
+            })),
+            total: routes.length,
+        };
+    }
+    async shapeCheck(repo, params) {
+        await this.ensureInitialized(repo);
+        const routeFilter = params.route ? `AND n.name CONTAINS $route` : '';
+        const queryParams = params.route ? { route: params.route } : {};
+        const allRoutes = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
+        const results = allRoutes
+            .filter((r) => ((r.responseKeys && r.responseKeys.length > 0) ||
+            (r.errorKeys && r.errorKeys.length > 0)) &&
+            r.consumers.length > 0)
+            .map((r) => {
+            // Keys already normalized by fetchRoutesWithConsumers (quotes stripped)
+            const responseKeys = r.responseKeys ?? [];
+            const errorKeys = r.errorKeys ?? [];
+            // Combined set: consumer accessing either success or error keys is valid
+            const allKnownKeys = new Set([...responseKeys, ...errorKeys]);
+            // Check each consumer's accessed keys against the route's response shape
+            const responseKeySet = new Set(responseKeys);
+            const consumers = r.consumers.map((c) => {
+                if (!c.accessedKeys || c.accessedKeys.length === 0) {
+                    return { name: c.name, filePath: c.filePath };
+                }
+                const mismatched = c.accessedKeys.filter((k) => !allKnownKeys.has(k));
+                // Keys in allKnownKeys but not in responseKeys — error-path access (e.g., .error from errorKeys)
+                const errorPathKeys = c.accessedKeys.filter((k) => allKnownKeys.has(k) && !responseKeySet.has(k));
+                const isMultiFetch = (c.fetchCount ?? 1) > 1;
+                return {
+                    name: c.name,
+                    filePath: c.filePath,
+                    accessedKeys: c.accessedKeys,
+                    ...(mismatched.length > 0
+                        ? {
+                            mismatched,
+                            mismatchConfidence: isMultiFetch ? 'low' : 'high',
+                        }
+                        : {}),
+                    ...(errorPathKeys.length > 0 ? { errorPathKeys } : {}),
+                    ...(isMultiFetch
+                        ? {
+                            attributionNote: `This file fetches ${c.fetchCount} routes — accessed keys may belong to a different route.`,
+                        }
+                        : {}),
+                };
+            });
+            const hasMismatches = consumers.some((c) => 'mismatched' in c && c.mismatched.length > 0);
+            return {
+                route: r.name,
+                method: r.method,
+                handler: r.filePath,
+                ...(responseKeys.length > 0 ? { responseKeys } : {}),
+                ...(errorKeys.length > 0 ? { errorKeys } : {}),
+                consumers,
+                ...(hasMismatches ? { status: 'MISMATCH' } : {}),
+            };
+        });
+        const mismatchCount = results.filter((r) => r.status === 'MISMATCH').length;
+        return {
+            routes: results,
+            total: results.length,
+            routesWithShapes: results.length,
+            ...(mismatchCount > 0 ? { mismatches: mismatchCount } : {}),
+            message: results.length === 0
+                ? 'No routes with both response shapes and consumers found.'
+                : mismatchCount > 0
+                    ? `Found ${results.length} route(s) with response shape data. ${mismatchCount} route(s) have consumer/shape mismatches.`
+                    : `Found ${results.length} route(s) with response shape data and consumers.`,
+        };
+    }
+    async toolMap(repo, params) {
+        await this.ensureInitialized(repo);
+        const toolFilter = params.tool ? `AND n.name CONTAINS $tool` : '';
+        const queryParams = params.tool ? { tool: params.tool } : {};
+        const rows = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (n:Tool)
+      WHERE n.id STARTS WITH 'Tool:' ${toolFilter}
+      RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description
+    `, queryParams);
+        if (rows.length === 0) {
+            return {
+                tools: [],
+                total: 0,
+                message: params.tool ? `No tools matching "${params.tool}"` : 'No tool definitions found.',
+            };
+        }
+        const toolIds = rows.map((r) => r.id ?? r[0]);
+        const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, toolIds);
+        return {
+            tools: rows.map((r) => {
+                const id = r.id ?? r[0];
+                return {
+                    name: r.name ?? r[1],
+                    filePath: r.filePath ?? r[2],
+                    description: (r.description ?? r[3] ?? '').slice(0, 200),
+                    flows: flowMap.get(id) || [],
+                };
+            }),
+            total: rows.length,
+        };
+    }
+    async apiImpact(repo, params) {
+        await this.ensureInitialized(repo);
+        if (!params.route && !params.file) {
+            return { error: 'Either "route" or "file" parameter is required.' };
+        }
+        // If file is provided but route is not, look up the route by file path
+        let routeFilter = '';
+        const queryParams = {};
+        if (params.route) {
+            routeFilter = `AND n.name CONTAINS $route`;
+            queryParams.route = params.route;
+        }
+        else if (params.file) {
+            routeFilter = `AND n.filePath CONTAINS $file`;
+            queryParams.file = params.file;
+        }
+        // After #2302 the same URL/handler can expose one Route node per HTTP verb.
+        // An optional `method` narrows to that one verb so the response collapses to
+        // the singular shape. A method-agnostic route (method `'*'`, e.g. a Django
+        // function view) matches any selector; verbless routes (null method) never do.
+        // `method` arrives unvalidated from the MCP envelope (the JSON schema is
+        // advisory), so reject a non-string verb with a structured error instead of
+        // throwing on `.toUpperCase()`; empty/whitespace collapses to no selector.
+        const rawMethod = params.method;
+        if (rawMethod !== undefined && typeof rawMethod !== 'string') {
+            return { error: '"method" must be a string (e.g. "GET", "POST").' };
+        }
+        const wantedMethod = typeof rawMethod === 'string' ? rawMethod.trim().toUpperCase() || undefined : undefined;
+        const matched = await this.fetchRoutesWithConsumers(repo.lbugPath, routeFilter, queryParams);
+        const routes = matched.filter((r) => !wantedMethod || r.method === '*' || r.method?.toUpperCase() === wantedMethod);
+        if (routes.length === 0) {
+            const target = params.route || params.file;
+            // Only append the verb when the URL/file matched routes but none used it;
+            // a non-existent URL/file gets the plain "no routes found" message.
+            const verb = wantedMethod && matched.length > 0 ? ` with method "${wantedMethod}"` : '';
+            return { error: `No routes found matching "${target}"${verb}.` };
+        }
+        const flowMap = await this.fetchLinkedFlowsBatch(repo.lbugPath, routes.map((r) => r.id));
+        // Count verbs per handler from the FULL match (before the method filter) so a
+        // method-scoped query still flags a multi-verb handler's partial middleware.
+        const routeCountByHandler = new Map();
+        for (const r of matched) {
+            if (r.filePath) {
+                routeCountByHandler.set(r.filePath, (routeCountByHandler.get(r.filePath) ?? 0) + 1);
+            }
+        }
+        const results = routes.map((r) => {
+            // Keys already normalized by fetchRoutesWithConsumers (quotes stripped)
+            const responseKeys = r.responseKeys ?? [];
+            const errorKeys = r.errorKeys ?? [];
+            const allKnownKeys = new Set([...responseKeys, ...errorKeys]);
+            // Build consumer list with mismatch detection
+            const consumers = r.consumers.map((c) => ({
+                name: c.name,
+                file: c.filePath,
+                accesses: c.accessedKeys ?? [],
+                ...(c.fetchCount && c.fetchCount > 1
+                    ? {
+                        attributionNote: `This file fetches ${c.fetchCount} routes — accessed keys may belong to a different route.`,
+                    }
+                    : {}),
+            }));
+            // Detect mismatches: consumer accesses keys not in response shape
+            const mismatches = [];
+            if (allKnownKeys.size > 0) {
+                for (const c of r.consumers) {
+                    if (!c.accessedKeys)
+                        continue;
+                    const isMultiFetch = (c.fetchCount ?? 1) > 1;
+                    for (const key of c.accessedKeys) {
+                        if (!allKnownKeys.has(key)) {
+                            mismatches.push({
+                                consumer: c.filePath,
+                                field: key,
+                                reason: 'accessed but not in response shape',
+                                confidence: isMultiFetch ? 'low' : 'high',
+                            });
+                        }
+                    }
+                }
+            }
+            const flows = flowMap.get(r.id) || [];
+            const consumerCount = r.consumers.length;
+            // Risk level heuristic
+            let riskLevel;
+            if (consumerCount >= 10) {
+                riskLevel = 'HIGH';
+            }
+            else if (consumerCount >= 4) {
+                riskLevel = 'MEDIUM';
+            }
+            else {
+                riskLevel = 'LOW';
+            }
+            // Bump up one level if mismatches exist
+            if (mismatches.length > 0) {
+                if (riskLevel === 'LOW')
+                    riskLevel = 'MEDIUM';
+                else if (riskLevel === 'MEDIUM')
+                    riskLevel = 'HIGH';
+            }
+            const warning = consumerCount > 0
+                ? `Changing response shape will affect ${consumerCount} component${consumerCount === 1 ? '' : 's'}`
+                : undefined;
+            // Flag when middleware was detected but handler exports multiple HTTP methods
+            // (middleware chain may only reflect one export)
+            const middlewareArr = r.middleware || [];
+            const handlerRouteCount = r.filePath ? (routeCountByHandler.get(r.filePath) ?? 1) : 1;
+            const middlewarePartial = middlewareArr.length > 0 && handlerRouteCount > 1;
+            return {
+                route: r.name,
+                method: r.method,
+                handler: r.filePath,
+                responseShape: {
+                    success: responseKeys,
+                    error: errorKeys,
+                },
+                middleware: middlewareArr,
+                ...(middlewarePartial
+                    ? {
+                        middlewareDetection: 'partial',
+                        middlewareNote: 'Middleware captured from the first route export only — other route exports in this handler may use different middleware chains.',
+                    }
+                    : {}),
+                consumers,
+                ...(mismatches.length > 0 ? { mismatches } : {}),
+                executionFlows: flows,
+                impactSummary: {
+                    directConsumers: consumerCount,
+                    affectedFlows: flows.length,
+                    riskLevel,
+                    ...(warning ? { warning } : {}),
+                },
+            };
+        });
+        // If a single route was targeted, return it directly (not wrapped in array)
+        if (results.length === 1) {
+            return results[0];
+        }
+        return { routes: results, total: results.length };
+    }
+    // ─── Direct Graph Queries (for resources.ts) ────────────────────
+    /**
+     * Query clusters (communities) directly from graph.
+     * Used by getClustersResource — avoids legacy overview() dispatch.
+     */
+    async queryClusters(repoName, limit = 100) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo);
+        try {
+            const rawLimit = Math.max(limit * 5, 200);
+            const clusters = await (0, pool_adapter_js_1.executeQuery)(repo.lbugPath, `
+        MATCH (c:Community)
+        RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+        ORDER BY c.symbolCount DESC, c.id
+        LIMIT ${rawLimit}
+      `);
+            const rawClusters = clusters.map((c) => ({
+                id: c.id || c[0],
+                label: c.label || c[1],
+                heuristicLabel: c.heuristicLabel || c[2],
+                cohesion: c.cohesion || c[3],
+                symbolCount: c.symbolCount || c[4],
+            }));
+            return { clusters: this.aggregateClusters(rawClusters).slice(0, limit) };
+        }
+        catch {
+            return { clusters: [] };
+        }
+    }
+    /**
+     * Query processes directly from graph.
+     * Used by getProcessesResource — avoids legacy overview() dispatch.
+     */
+    async queryProcesses(repoName, limit = 50) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo);
+        try {
+            const processes = await (0, pool_adapter_js_1.executeQuery)(repo.lbugPath, `
+        MATCH (p:Process)
+        RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+        ORDER BY p.stepCount DESC, p.id
+        LIMIT ${limit}
+      `);
+            return {
+                processes: processes.map((p) => ({
+                    id: p.id || p[0],
+                    label: p.label || p[1],
+                    heuristicLabel: p.heuristicLabel || p[2],
+                    processType: p.processType || p[3],
+                    stepCount: p.stepCount || p[4],
+                })),
+            };
+        }
+        catch {
+            return { processes: [] };
+        }
+    }
+    /**
+     * Query cluster detail (members) directly from graph.
+     * Used by getClusterDetailResource.
+     */
+    async queryClusterDetail(name, repoName) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo);
+        const clusters = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (c:Community)
+      WHERE c.label = $clusterName OR c.heuristicLabel = $clusterName
+      RETURN c.id AS id, c.label AS label, c.heuristicLabel AS heuristicLabel, c.cohesion AS cohesion, c.symbolCount AS symbolCount
+    `, { clusterName: name });
+        if (clusters.length === 0)
+            return { error: `Cluster '${name}' not found` };
+        const rawClusters = clusters.map((c) => ({
+            id: c.id || c[0],
+            label: c.label || c[1],
+            heuristicLabel: c.heuristicLabel || c[2],
+            cohesion: c.cohesion || c[3],
+            symbolCount: c.symbolCount || c[4],
+        }));
+        let totalSymbols = 0, weightedCohesion = 0;
+        for (const c of rawClusters) {
+            const s = c.symbolCount || 0;
+            totalSymbols += s;
+            weightedCohesion += (c.cohesion || 0) * s;
+        }
+        const members = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+      WHERE c.label = $clusterName OR c.heuristicLabel = $clusterName
+      RETURN DISTINCT n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+      ORDER BY filePath, name, type
+      LIMIT 30
+    `, { clusterName: name });
+        return {
+            cluster: {
+                id: rawClusters[0].id,
+                label: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                heuristicLabel: rawClusters[0].heuristicLabel || rawClusters[0].label,
+                cohesion: totalSymbols > 0 ? weightedCohesion / totalSymbols : 0,
+                symbolCount: totalSymbols,
+                subCommunities: rawClusters.length,
+            },
+            members: members.map((m) => ({
+                name: m.name || m[0],
+                type: m.type || m[1],
+                filePath: m.filePath || m[2],
+            })),
+        };
+    }
+    /**
+     * Query process detail (steps) directly from graph.
+     * Used by getProcessDetailResource.
+     */
+    async queryProcessDetail(name, repoName) {
+        const repo = await this.resolveRepo(repoName);
+        await this.ensureInitialized(repo);
+        const processes = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (p:Process)
+      WHERE p.label = $processName OR p.heuristicLabel = $processName
+      RETURN p.id AS id, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount
+      ORDER BY id
+      LIMIT 1
+    `, { processName: name });
+        if (processes.length === 0)
+            return { error: `Process '${name}' not found` };
+        const proc = processes[0];
+        const procId = proc.id || proc[0];
+        const steps = await (0, pool_adapter_js_1.executeParameterized)(repo.lbugPath, `
+      MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p {id: $procId})
+      RETURN n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, r.step AS step
+      ORDER BY r.step
+    `, { procId });
+        return {
+            process: {
+                id: procId,
+                label: proc.label || proc[1],
+                heuristicLabel: proc.heuristicLabel || proc[2],
+                processType: proc.processType || proc[3],
+                stepCount: proc.stepCount || proc[4],
+            },
+            steps: steps.map((s) => ({
+                step: s.step || s[3],
+                name: s.name || s[0],
+                type: s.type || s[1],
+                filePath: s.filePath || s[2],
+            })),
+        };
+    }
+    async disconnect() {
+        await (0, pool_adapter_js_1.closeLbug)(); // close all connections
+        // Note: we intentionally do NOT call disposeEmbedder() here.
+        // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs,
+        // and importing the embedder module on Node v24+ crashes if onnxruntime
+        // was never loaded during the session. Since process.exit(0) follows
+        // immediately after disconnect(), the OS reclaims everything. See #38, #89.
+        this.repos.clear();
+        this.contextCache.clear();
+        this.initializedRepos.clear();
+    }
+}
+exports.LocalBackend = LocalBackend;