gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/mcp/local/aop-metadata.js

@@ -0,0 +1,227 @@
+import { executeParameterized } from '../../core/lbug/pool-adapter.js';
+import { decodeSpringAopReason, } from '../../core/ingestion/frameworks/spring/aop.js';
+const SUPPORTED_SYMBOL_TYPES = new Set(['Class', 'Interface', 'Method', 'CodeElement']);
+const QUERY_RESULT_LIMIT = 1_000;
+const QUERY_FETCH_LIMIT = QUERY_RESULT_LIMIT + 1;
+function readRowValue(row, name, index) {
+    if (typeof row === 'object' && row !== null && name in row) {
+        return row[name];
+    }
+    return Array.isArray(row) ? row[index] : undefined;
+}
+function readRequiredString(row, name, index) {
+    const value = readRowValue(row, name, index);
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readOptionalString(row, name, index) {
+    const value = readRowValue(row, name, index);
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function normalizeRelationshipRow(row) {
+    const sourceId = readRequiredString(row, 'sourceId', 0);
+    const targetId = readRequiredString(row, 'targetId', 3);
+    if (sourceId === undefined || targetId === undefined)
+        return undefined;
+    const sourceName = readOptionalString(row, 'sourceName', 1);
+    const sourceFilePath = readOptionalString(row, 'sourceFilePath', 2);
+    const targetName = readOptionalString(row, 'targetName', 4);
+    const targetFilePath = readOptionalString(row, 'targetFilePath', 5);
+    return {
+        sourceId,
+        ...optionalField('sourceName', sourceName),
+        ...optionalField('sourceFilePath', sourceFilePath),
+        targetId,
+        ...optionalField('targetName', targetName),
+        ...optionalField('targetFilePath', targetFilePath),
+        reason: readRowValue(row, 'reason', 6),
+    };
+}
+function optionalField(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function stableDedupe(values, keyOf) {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(keyOf(value), value);
+    return [...unique.entries()]
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([, value]) => value);
+}
+const RELATIONSHIP_PROJECTION = `
+  RETURN source.id AS sourceId, source.name AS sourceName, source.filePath AS sourceFilePath,
+         target.id AS targetId, target.name AS targetName, target.filePath AS targetFilePath,
+         r.reason AS reason, r.step AS step
+`;
+const DETERMINISTIC_RELATIONSHIP_ORDER = 'ORDER BY sourceId, targetId, reason, step';
+/**
+ * Read additive Spring proxy/advice metadata for context and impact results.
+ *
+ * The helper intentionally trusts only versioned reasons accepted by the
+ * shared decoder. Other DECLARES edges (for example Spring Bean factories)
+ * and malformed/forward-version evidence are ignored. Query failures are
+ * fail-soft because older or partially upgraded indexes must remain readable.
+ */
+export async function querySpringAopMetadata(lbugPath, symbolId, symbolType) {
+    if (!SUPPORTED_SYMBOL_TYPES.has(symbolType))
+        return undefined;
+    try {
+        const [outgoingAdviceRows, incomingAdviceRows, outgoingPointcutRows, incomingPointcutRows] = await Promise.all([
+            executeParameterized(lbugPath, `MATCH (source {id: $symbolId})-[r:CodeRelation]->(target)
+           WHERE r.type = 'ADVISED_BY'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            executeParameterized(lbugPath, `MATCH (source)-[r:CodeRelation]->(target {id: $symbolId})
+           WHERE r.type = 'ADVISED_BY'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            executeParameterized(lbugPath, `MATCH (source {id: $symbolId})-[r:CodeRelation]->(target:CodeElement)
+           WHERE r.type = 'DECLARES'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            executeParameterized(lbugPath, `MATCH (source)-[r:CodeRelation]->(target:CodeElement {id: $symbolId})
+           WHERE r.type = 'DECLARES'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+        ]);
+        const behaviors = [];
+        const advices = [];
+        const resolvedPointcuts = [];
+        const unresolvedPointcuts = [];
+        const aspects = [];
+        const truncated = [
+            outgoingAdviceRows,
+            incomingAdviceRows,
+            outgoingPointcutRows,
+            incomingPointcutRows,
+        ].some((rows) => rows.length >= QUERY_FETCH_LIMIT);
+        let queriedSymbolIsAdvisedSource = false;
+        for (const [rows, isOutgoing] of [
+            [outgoingAdviceRows, true],
+            [incomingAdviceRows, false],
+        ]) {
+            for (const rawRow of rows.slice(0, QUERY_RESULT_LIMIT)) {
+                const row = normalizeRelationshipRow(rawRow);
+                if (row === undefined)
+                    continue;
+                const reason = decodeSpringAopReason(row.reason);
+                if (reason?.kind === 'behavior') {
+                    if (isOutgoing)
+                        queriedSymbolIsAdvisedSource = true;
+                    behaviors.push({
+                        annotation: reason.annotation,
+                        behavior: reason.behavior,
+                        declaredOn: reason.declaredOn,
+                        activation: reason.activation,
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'advice') {
+                    if (isOutgoing)
+                        queriedSymbolIsAdvisedSource = true;
+                    advices.push({
+                        annotation: reason.annotation,
+                        advice: reason.advice,
+                        pointcut: reason.pointcut,
+                        match: reason.match,
+                        activation: reason.activation,
+                        adviceId: row.targetId,
+                        ...optionalField('adviceName', row.targetName),
+                        ...optionalField('adviceFilePath', row.targetFilePath),
+                        advisedId: row.sourceId,
+                        ...optionalField('advisedName', row.sourceName),
+                        ...optionalField('advisedFilePath', row.sourceFilePath),
+                    });
+                }
+            }
+        }
+        for (const rows of [outgoingPointcutRows, incomingPointcutRows]) {
+            for (const rawRow of rows.slice(0, QUERY_RESULT_LIMIT)) {
+                const row = normalizeRelationshipRow(rawRow);
+                if (row === undefined)
+                    continue;
+                const reason = decodeSpringAopReason(row.reason);
+                if (reason?.kind === 'aspect') {
+                    aspects.push({
+                        annotation: reason.annotation,
+                        activation: reason.activation,
+                        registration: reason.registration,
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'pointcut' &&
+                    reason.match === 'static' &&
+                    reason.resolution === 'resolved' &&
+                    typeof reason.pointcut === 'string') {
+                    resolvedPointcuts.push({
+                        annotation: reason.annotation,
+                        pointcut: reason.pointcut,
+                        match: reason.match,
+                        resolution: reason.resolution,
+                        adviceId: row.sourceId,
+                        ...optionalField('adviceName', row.sourceName),
+                        ...optionalField('adviceFilePath', row.sourceFilePath),
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'pointcut' && reason.match === 'unresolved') {
+                    unresolvedPointcuts.push({
+                        annotation: reason.annotation,
+                        pointcut: reason.pointcut,
+                        adviceId: row.sourceId,
+                        ...optionalField('adviceName', row.sourceName),
+                        ...optionalField('adviceFilePath', row.sourceFilePath),
+                        evidenceId: row.targetId,
+                    });
+                }
+            }
+        }
+        const dedupedAspects = stableDedupe(aspects, (aspect) => JSON.stringify([aspect.annotation, aspect.evidenceId]));
+        const dedupedBehaviors = stableDedupe(behaviors, (behavior) => JSON.stringify([
+            behavior.behavior,
+            behavior.annotation,
+            behavior.declaredOn,
+            behavior.evidenceId,
+        ]));
+        const dedupedAdvices = stableDedupe(advices, (advice) => JSON.stringify([advice.advisedId, advice.adviceId, advice.advice, advice.pointcut]));
+        const dedupedPointcuts = stableDedupe(unresolvedPointcuts, (pointcut) => JSON.stringify([
+            pointcut.adviceId,
+            pointcut.evidenceId,
+            pointcut.annotation,
+            pointcut.pointcut,
+        ]));
+        const dedupedResolvedPointcuts = stableDedupe(resolvedPointcuts, (pointcut) => JSON.stringify([
+            pointcut.adviceId,
+            pointcut.evidenceId,
+            pointcut.annotation,
+            pointcut.pointcut,
+        ]));
+        if (dedupedAspects.length === 0 &&
+            dedupedBehaviors.length === 0 &&
+            dedupedAdvices.length === 0 &&
+            dedupedResolvedPointcuts.length === 0 &&
+            dedupedPointcuts.length === 0) {
+            return undefined;
+        }
+        return {
+            framework: 'spring',
+            ...(queriedSymbolIsAdvisedSource ? { proxied: 'possible' } : {}),
+            ...(truncated ? { truncated: true } : {}),
+            ...(dedupedAspects[0] === undefined ? {} : { aspect: dedupedAspects[0] }),
+            behaviors: dedupedBehaviors,
+            advices: dedupedAdvices,
+            resolvedPointcuts: dedupedResolvedPointcuts,
+            unresolvedPointcuts: dedupedPointcuts,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp/local/bean-metadata.d.ts

@@ -0,0 +1,3 @@
+import { type SpringBeanMetadata } from '../../core/ingestion/frameworks/spring/bean-catalog.js';
+import { type SpringBeanFactoryMetadata } from '../../core/ingestion/frameworks/spring/bean-factories.js';
+export declare function queryClassBeanMetadata(lbugPath: string, symbolId: string, symbolType: string): Promise<SpringBeanMetadata | SpringBeanFactoryMetadata | undefined>;

package/dist/mcp/local/bean-metadata.js

@@ -0,0 +1,46 @@
+import { executeParameterized } from '../../core/lbug/pool-adapter.js';
+import { deriveSpringBeanMetadata, } from '../../core/ingestion/frameworks/spring/bean-catalog.js';
+import { decodeSpringBeanFactoryReason, } from '../../core/ingestion/frameworks/spring/bean-factories.js';
+export async function queryClassBeanMetadata(lbugPath, symbolId, symbolType) {
+    if (symbolType !== 'Class' && symbolType !== 'Method' && symbolType !== 'CodeElement') {
+        return undefined;
+    }
+    try {
+        if (symbolType !== 'Class') {
+            const pattern = symbolType === 'Method'
+                ? 'MATCH (m:Method {id: $symbolId})-[r:CodeRelation]->(b:CodeElement)'
+                : 'MATCH (m:Method)-[r:CodeRelation]->(b:CodeElement {id: $symbolId})';
+            // determinism: probe — PK-anchored singleton. A @Bean factory's declaration
+            // node id is derived from the declaring method's id
+            // (`CodeElement:spring-bean:<methodId>`, see bean-factories.ts), so exactly
+            // one DECLARES edge with this reason prefix exists per anchored endpoint,
+            // whichever end `$symbolId` pins.
+            const rows = await executeParameterized(lbugPath, `${pattern}
+         WHERE r.type = 'DECLARES'
+           AND r.reason STARTS WITH 'spring-bean-factory:'
+         RETURN r.reason AS reason
+         LIMIT 1`, { symbolId });
+            const row = rows[0];
+            return row === undefined ? undefined : decodeSpringBeanFactoryReason(row.reason ?? row[0]);
+        }
+        // determinism: probe — PK-anchored singleton. `$symbolId` is a node primary
+        // key, so at most one Class row can match and the LIMIT never chooses.
+        const rows = await executeParameterized(lbugPath, `
+      MATCH (c:Class {id: $symbolId})
+      RETURN c.frameworkAnnotations AS frameworkAnnotations
+      LIMIT 1
+    `, { symbolId });
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        const value = row.frameworkAnnotations ?? row[0];
+        if (!Array.isArray(value))
+            return undefined;
+        return deriveSpringBeanMetadata(value.filter((annotation) => typeof annotation === 'string'));
+    }
+    catch {
+        // Older or partially upgraded indexes may not have the column. This
+        // enrichment is additive, so context and impact must still succeed.
+        return undefined;
+    }
+}

package/dist/mcp/local/local-backend.d.ts

@@ -7,11 +7,12 @@
  */
 import { type RegistryEntry, type BranchSummary } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
+import { type StalenessInfo } from '../../core/git-staleness.js';
 /**
  * Quick test-file detection for filtering impact results.
  * Matches common test file patterns across all supported languages.
  */
-export declare function isTestFilePath(filePath: string): boolean;
+export declare function isTestFilePath(filePath: string | null | undefined): boolean;
 /** Valid LadybugDB node labels for safe Cypher query construction */
 export declare const VALID_NODE_LABELS: Set<string>;
 /** Valid relation types for impact analysis filtering */
@@ -55,6 +56,90 @@ export interface CodebaseContext {
         processCount: number;
     };
 }
+/** Collapse dropped-site boundary notes into an epistemic verdict: any note at
+ *  all means the count is a lower bound, none means it is exact (#2744). */
+/**
+ * Why a count is a lower bound, as a machine-readable split.
+ *
+ * `epistemic` is a single enum and `boundaries` is prose, so a consumer that is
+ * not a human — a coding agent gating its own edits on this result — can tell
+ * THAT the answer is short but not WHY, and cannot branch on the difference.
+ * The two causes are independent and have opposite remedies:
+ *
+ * - `receiverTyping` — the analyzer dropped call sites because it could not
+ *   establish the receiver's type. A resolver defect. Fixable, and shrinking:
+ *   this is the population the structural-receiver work targets.
+ * - `dispatchBoundary` — the symbol sits behind an interface with real
+ *   consumers or multiple implementations, so callers binding through a DI
+ *   container or dynamic dispatch are genuinely untraceable statically. NOT a
+ *   defect; a compiler would refuse here too.
+ *
+ * Collapsing them told the reader "impact may be higher" for both, which made
+ * the fixable cause indistinguishable from the irreducible one — and made
+ * "the hedge should stop appearing" an unfalsifiable goal, because there was no
+ * way to see which producer was still firing.
+ *
+ * Every field counts MISSING THINGS, never notes. The unit is stated per field
+ * because the two producers can only measure at different granularities (see
+ * `dispatchBoundary`), and a consumer comparing the numbers has to know which
+ * it is holding. Counting notes here is the specific mistake to avoid: there is
+ * one note per symbol name / per boundary node, so a note count reports the
+ * number of SENTENCES, which has no relation to how much is missing.
+ */
+export interface EpistemicCauses {
+    /**
+     * Call SITES dropped at index time because the receiver's type could not be
+     * established. Unit: call sites, taken from the index's
+     * `unresolvedReceiverMembers` summary — the same number the prose note quotes.
+     */
+    readonly receiverTyping: number;
+    /**
+     * Symbols on the far side of a dispatch boundary that the traversal could not
+     * attribute to the queried symbol: implementations plus interface-level
+     * consumers, summed over the boundary nodes that were flagged.
+     *
+     * Unit: SYMBOLS, not call sites — deliberately, because a call-site count is
+     * not derivable on this side. The graph does not retain per-site multiplicity
+     * for these edges: consumers are counted with `COUNT(DISTINCT other.id)`, and
+     * languages that set `collapseMemberCallsByCallerTarget` emit one CALLS edge
+     * per (caller, target) pair no matter how many syntactic sites exist. A
+     * symbol reachable through two flagged boundary nodes is counted once per
+     * node, so this is itself a lower bound.
+     *
+     * It is still directly comparable in magnitude with `receiverTyping` — both
+     * answer "how much is missing" — which `boundaries.length` was not.
+     */
+    readonly dispatchBoundary: number;
+    /**
+     * Call sites whose receiver was rooted OUTSIDE the indexed program —
+     * `System.out.println`, `fetch(...)`, `os.environ.*`. Reported, but NOT a
+     * reason the count is short: there is no in-graph node an edge could have
+     * reached, so the analysis is complete for the program as given.
+     *
+     * Surfaced so "no uncertainty" is distinguishable from "we judged 76 calls to
+     * be outside the program". A compiler resolves these against the JDK / BCL /
+     * lib.d.ts; lacking those, this number IS the boundary.
+     *
+     * Unit: call sites — same unit and same source as `receiverTyping`.
+     */
+    readonly externalBoundary: number;
+    /**
+     * Interface-satisfaction checks the ANALYZER could not complete, on a
+     * boundary this query crossed (#2873). Unit: unjudged (interface, candidate
+     * type) pairs.
+     *
+     * Distinct from every slot above, which count facts the analyzer decided and
+     * then could not attribute. This one counts questions it never answered — a
+     * type in a required signature had no identity to compare, so no IMPLEMENTS
+     * edge was minted and no dispatch boundary exists for the walk to notice. It
+     * is the one cause that makes a result short WITHOUT leaving a trace in the
+     * graph, which is why it has to be read from the index metadata instead.
+     *
+     * Zero on any index written before the field existed; that reads the same as
+     * "nothing was undecided", and a re-index is what tells the two apart.
+     */
+    readonly undecidedSatisfaction: number;
+}
 interface RepoHandle {
     id: string;
     name: string;
@@ -86,6 +171,7 @@ interface RepoHandle {
  * and cannot be changed mid-process.
  */
 export declare function resolveWorktreeCwd(repoPath: string, launchCwd: string): string;
+export declare function buildDetectChangesDiffArgs(scope: string, baseRef?: string): string[] | null;
 /**
  * Length of the path-derived suffix appended to a colliding repo id.
  * Exported so tests can pin the suffix shape without re-deriving the
@@ -140,13 +226,24 @@ export interface ListReposPagination {
     /** Offset to request next; present only when `hasMore` is true. */
     nextOffset?: number;
 }
+/**
+ * #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.
+ */
+export declare function attachToolStaleness(result: unknown, staleness: StalenessInfo | undefined): unknown;
 export declare class LocalBackend {
+    private static readonly TOOL_STALENESS_TTL_MS;
     private repos;
     private contextCache;
     private initializedRepos;
     private reinitPromises;
     private lastStalenessCheck;
-    private lastObservedIndexedAt;
+    private toolStalenessCache;
+    private lastObservedPoolState;
+    /** Merge-patch one poolKey's observed state, preserving fields not passed. */
+    private setObservedState;
     private groupToolSvc;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -168,6 +265,32 @@ export declare class LocalBackend {
      * degradation is visible once instead of silent.
      */
     private warnedMissingEmbeddingStack;
+    /**
+     * Width the semantic lane last produced a QUERY vector at for an index, keyed
+     * by `lbugPath` (like `lastObservedPoolState`, and for the same reason: branch
+     * handles are rebuilt by `applyBranchScope` on every `resolveRepo`, so state
+     * hung off the handle would not survive to the next call).
+     *
+     * Exists so `query()` can raise the vector-column drift warning (#2798) ONLY
+     * where a width actually matters — a call that embedded something. The lane
+     * returns before importing the embedder when the index holds no vectors, and
+     * swallows an unavailable/pruned embedder into `[]`; a width complaint about
+     * either is noise about a comparison that never happened, and every index
+     * analyzed without `--embeddings` would carry it on every query.
+     *
+     * Recorded rather than recomputed at the warning site because the comparand
+     * must be the width the CAST actually binds — `getEmbeddingDims()` (the HTTP
+     * dimensions, else the local model's fixed 384), NOT `schema.ts`'s
+     * env-derived `EMBEDDING_DIMS`. Those two disagree exactly when
+     * `GITNEXUS_EMBEDDING_DIMS` is set on a server embedding LOCALLY, where the
+     * env value is the one the query path ignores — comparing against it would
+     * report drift on a lane that is working fine.
+     *
+     * Written only on definite outcomes (set once a vector exists, deleted where
+     * the lane provably embedded nothing), so concurrent queries against one
+     * index write the same value and an entry never outlives the fact it records.
+     */
+    private lastQueryEmbeddingDims;
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -364,6 +487,24 @@ export declare class LocalBackend {
      * re-shell-out to git.
      */
     private maybeWarnSiblingDrift;
+    /**
+     * #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.
+     */
+    private withToolStaleness;
+    /**
+     * #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.
+     */
+    private stalenessForTool;
     callTool(method: string, params: any): Promise<any>;
     /** Check repository graph invariants that are suitable for CI gating. */
     private check;
@@ -402,10 +543,15 @@ export declare class LocalBackend {
      * 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 five 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.
+     * 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
@@ -599,7 +745,22 @@ export declare class LocalBackend {
      * Never throws: on query error it returns 'exact', so it can only add signal,
      * never suppress a result.
      */
+    /**
+     * Fields the analyzer declined to link because every definition of the name
+     * lives in another language (R3-1), keyed by name.
+     *
+     * Cached per index version. `ensureInitialized` deliberately avoids a
+     * per-call `loadMeta` because every tool call routes through it; this is one
+     * small read per (index, indexedAt), which re-reads exactly when a re-analyze
+     * could have changed the answer and never otherwise.
+     */
+    private readonly crossLanguagePropertyCache;
+    private crossLanguagePropertiesFor;
     private computeEpistemicBoundary;
+    /** Declaring types of a method, for matching against a candidate-keyed
+     *  record. One hop, asked only for methods, and only when a record exists to
+     *  match against. */
+    private owningTypeNames;
     /**
      * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
      */