adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/graph/builder.py

@@ -0,0 +1,2670 @@
+"""Call graph builder.
+
+Constructs the call graph from parsed symbols and detected patterns.
+Equivalent to drift_core/src/callgraph.rs.
+"""
+
+from __future__ import annotations
+
+import os
+import logging
+import re
+from collections import defaultdict, deque, Counter
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple, Any
+import networkx as nx
+
+from adl_drift.utils.types import LOCALS_MARKER, Symbol, AnalysisResult, Pattern
+from adl_drift.utils.config import find_project_root as _find_project_root
+from adl_drift.graph.node import GraphNode, NodeType
+from adl_drift.graph.edges import GraphEdge, EdgeType
+from adl_drift.lang.base import CallResolver, CFGConfig, ResolverConfig
+from adl_drift.parser.core import ParseResult, PythonParser
+
+
+# Bump this whenever resolver semantics or graph structure change in a way
+# that makes previously persisted graphs wrong (new/removed edge kinds,
+# resolution-strategy changes, node-id scheme changes). CortexMemory stamps
+# it into graph_metadata on save and invalidates any cached graph whose
+# stored version differs — so stale caches self-heal without a manual rescan.
+# History: 1 = pre-P1.7 resolver; 2 = chained calls + builtin deny-list +
+# container-expansion impact (P1.6/P1.7/P2.7); 3 = structured imports
+# (relative-import resolution) + inheritance/super()/annotation-aware
+# resolution (P2.1/P2.2); 4 = REFERENCES / TYPE_OF / RETURNS usage edges
+# (P1.8); 5 = INSTANTIATES / OVERRIDES (P2.8); 6 = literal-candidate
+# CALLS/IMPORTS/REFERENCES edges (P2.13); 7 = DYNAMIC_ATTR edges (P2.14);
+# 8 = decorator stub/rebind resolution (P2.15);
+# 9 = nested same-name defs / scope-chain IDs (P2.17);
+# 10 = <locals> scope markers in node ids + qualified_name decoupling +
+#      scope-aware attribute ids (P1.10 steps 2+3, P3.13 fold-in);
+# 11 = ':' module/qualname id split (P1.10 step 4): symbol ids are
+#      "module:qualname" so a class ``b`` in ``a/__init__.py`` (``a:b``) can
+#      never collide with submodule ``a/b.py`` (``a.b``).
+# 13 = callable-dict dispatch with var aliasing + cross-scope closures (P2.22):
+#      `D = {k: self.h.handle}; fn = D.get(x); fn()` now emits CALLS to each
+#      resolved value, so entry points reach handlers through dict routers.
+# 16 = Java IMPLEMENTS hierarchy edges (P4.9).
+# 17 = optional erased-signature discriminator in symbol ids (P4.5).
+# 19 = Java compilation-unit imports + stable anonymous/compact-constructor ids (P4.5).
+# 20 = Java static-import call path binds only `static` members — an
+#      equally-named instance method is no longer a target (F-02); FUNCTION
+#      nodes now carry `java_is_static` metadata.
+# 21 = GraphNode.metadata (java_is_abstract/java_type_kind/java_return_type/
+#      java_is_static) is now persisted and restored on save_graph/load_graph
+#      (F-01) — older cached graphs have it silently dropped and must rebuild
+#      so P4.12 abstract-dispatch fan-out sees the real flags again.
+# 22 = Java generic-bound narrowing (`_collect_type_param_bounds`) now also
+#      reads enclosing class/interface/record `<T extends Bound>` type
+#      parameters, not just the method's own (F-04) — `class Client<T
+#      extends Stripe> { void run(T g) { g.charge(); } }` now resolves;
+#      older cached graphs are missing these CALLS edges and must rebuild.
+# 23 = normalize project roots and treat same-file Python rebinding as shadowing.
+# 24 = persist every source occurrence separately from deduplicated dependency
+#      edges, using exact CST byte ranges to distinguish nested fluent calls.
+# 25 = Java functional references/lambda target typing and callable-container
+#      dispatch edges (P4.13).
+# 26 = stable Java build-unit namespaces for independent nested Maven/Gradle
+#      roots, preventing legal duplicate FQNs from overwriting each other.
+# 27 = custom-named Gradle build units (``project.buildFileName``) participate
+#      in Java namespaces; cached root-scoped IDs must be rebuilt.
+# 28 = GraphNode gained ``end_line`` (symbol body end, from parse position) so
+#      drift_node/drift_search can size a source snippet to the real method
+#      length instead of a flat default; cached nodes predate the field.
+GRAPH_SCHEMA_VERSION = 28
+
+logger = logging.getLogger(__name__)
+
+class CallGraphBuilder:
+    """Builds a NetworkX directed graph from analysis results.
+
+    The graph captures:
+    - Which functions call which other functions
+    - Module import relationships
+    - Class containment hierarchies
+    - Async/await relationships
+    """
+
+    def __init__(
+        self,
+        project_root: Optional[Path] = None,
+        resolver_config: Optional[ResolverConfig] = None,
+        cfg_config: Optional[CFGConfig] = None,
+    ):
+        # P4.4: the active language's name-resolution policy. None until
+        # either passed explicitly (a backend's `resolver_config()`) or
+        # lazily defaulted to Python's on first `_get_resolver()` call — every
+        # pre-P4.4 call site constructs `CallGraphBuilder()` with no config
+        # and must keep getting Python behavior.
+        self.resolver_config = resolver_config
+        self._resolver: Optional[CallResolver] = None
+        # P4.6: the active language's CFG/taint tables + mechanics factories.
+        # Same lazy-default story as `resolver_config` above — every pre-P4.6
+        # call site constructs `CallGraphBuilder()`/`from_results()` with no
+        # config and must keep getting Python behavior via `_get_cfg_config()`.
+        self.cfg_config = cfg_config
+        self._taint_strategy = None
+        # MultiDiGraph: parallel edges of different types between the same
+        # node pair must coexist (CALLS+AWAITS, TYPE_OF+RETURNS, ...) — a
+        # plain DiGraph silently overwrites the first edge's attributes.
+        self.graph = nx.MultiDiGraph()
+        self._nodes: Dict[str, GraphNode] = {}
+        self._edges: List[GraphEdge] = []
+        self._edge_keys: Set[Tuple[str, str, EdgeType]] = set()
+        # Dependency edges above intentionally stay unique for traversal and
+        # impact analysis. This parallel collection preserves every concrete
+        # source occurrence for metrics, taint and IDE positions.
+        self._edge_occurrences: List[GraphEdge] = []
+        self._occurrence_keys: Set[Tuple[Any, ...]] = set()
+        self.project_root = Path(project_root).resolve() if project_root is not None else None
+        # Module/package ownership is independent of emitted symbols: valid
+        # compilation units such as package-info.java may contain none.
+        self._module_owners: Dict[str, Set[str]] = {}
+        self.backend_names: Set[str] = set()
+        self.indexed_extensions: Set[str] = set()
+        self._project_languages: Optional[Set[str]] = None
+        self._module_suffix_index: Optional[Dict[Tuple[str, str], str]] = None
+        self._qualified_lookup_cache: Dict[Tuple[str, str], Optional[str]] = {}
+        self._global_dotted_index: Optional[Dict[str, List[str]]] = None
+        # simple CLASS name -> its node id if globally unique, else None.
+        # Lazily built/invalidated exactly like `_global_dotted_index` above.
+        self._class_by_simple_name_index: Optional[Dict[str, Optional[str]]] = None
+        self._classes_by_simple_name: Dict[str, List[Tuple[str, str]]] = {}
+        self._java_build_module_roots: Optional[List[Tuple[Path, str]]] = None
+        self._java_build_module_cache: Dict[str, Optional[str]] = {}
+        self._java_build_module_dir_cache: Dict[str, Path] = {}
+        self._java_namespace_visibility: Optional[Dict[str, Set[str]]] = None
+        # Pending relationship data collected during add_file_result,
+        # resolved later by resolve_relationships().
+        # class_id -> (superclass_name_list, file_path, line)
+        self._pending_inherits: Dict[str, Tuple[List[str], str, int]] = {}
+        self._pending_implements: Dict[str, Tuple[List[str], str, int]] = {}
+        # symbol_id -> (decorator_text_list, module_name, file_path, line)
+        self._pending_decorators: Dict[str, Tuple[List[str], str, str, int]] = {}
+        # file_path -> (module_id, import_map {binding: dotted_path})
+        self._pending_imports: Dict[str, Tuple[str, Dict[str, str]]] = {}
+        # P2.15: decorated_fn_node_id → (stub_attrs, rebound_class_id)
+        # Populated by resolve_decorator_types(); consumed by _resolve_target().
+        self._decorator_rebirds: Dict[str, Tuple[Optional[Set[str]], Optional[str]]] = {}
+        # P1.10 step 1: collision tripwire side table. When _add_node sees an
+        # existing id with a different file or node type, the displaced node is
+        # kept here keyed by its location (Drift V3's location-identity
+        # pattern) instead of vanishing silently.
+        self.node_collisions: Dict[Tuple[str, int], GraphNode] = {}
+
+    # Dropped from the pickled snapshot `CortexMemory.save_graph` persists:
+    # per-language policy objects (they hold lambdas) and every cache that is
+    # rebuilt lazily from the nodes/edges, so an unpickled builder starts in
+    # the same state as one reloaded row by row.
+    _SNAPSHOT_EXCLUDED = frozenset({
+        "resolver_config", "_resolver", "cfg_config", "_taint_strategy",
+        "_project_languages", "_module_suffix_index", "_qualified_lookup_cache",
+        "_global_dotted_index", "_class_by_simple_name_index",
+        "_java_build_module_roots", "_java_build_module_cache",
+        "_java_build_module_dir_cache", "_java_namespace_visibility",
+    })
+
+    def __getstate__(self) -> Dict[str, Any]:
+        return {
+            name: value for name, value in self.__dict__.items()
+            if name not in self._SNAPSHOT_EXCLUDED
+        }
+
+    def __setstate__(self, state: Dict[str, Any]) -> None:
+        self.__dict__.update(CallGraphBuilder().__dict__)
+        self.__dict__.update(state)
+
+    def _get_resolver(self) -> CallResolver:
+        """P4.4: lazily build (and cache) this builder's `CallResolver`.
+
+        `self.resolver_config` is None for every pre-P4.4 call site
+        (`CallGraphBuilder()` with no args, still used throughout
+        `cli/commands.py`/`server/handlers.py`/`cortex/memory.py` — wiring
+        those through `lang.registry` is P4.8/P4.10, out of scope here) — in
+        that case default to Python's config, matching the behavior every
+        existing caller already depends on. A backend-supplied config
+        (`JavaBackend.resolver_config()`) builds its own resolver via
+        `ResolverConfig.resolver_factory`.
+        """
+        if self._resolver is None:
+            if self.resolver_config is None:
+                from adl_drift.lang.python.resolver import (
+                    default_python_resolver_config,
+                )
+                self.resolver_config = default_python_resolver_config()
+            if self.resolver_config.resolver_factory is None:
+                raise ValueError(
+                    "ResolverConfig has no resolver_factory — "
+                    "LanguageBackend.resolver_config() must set one "
+                    "(see lang/python/resolver.py::default_python_resolver_config)."
+                )
+            self._resolver = self.resolver_config.resolver_factory(
+                self, self.resolver_config
+            )
+        return self._resolver
+
+    def _get_cfg_config(self) -> CFGConfig:
+        """P4.6: lazily default `self.cfg_config` to Python's, mirroring
+        `_get_resolver()`'s fallback — every pre-P4.6 call site (no config
+        passed) keeps getting Python's CFG/taint tables."""
+        if self.cfg_config is None:
+            from adl_drift.lang.python.cfg import default_python_cfg_config
+            self.cfg_config = default_python_cfg_config()
+        return self.cfg_config
+
+    def _get_taint_strategy(self):
+        """P4.6: lazily build (and cache) this builder's `TaintStrategy`
+        (`detectors/taint.py`) via `CFGConfig.taint_strategy_factory`."""
+        if self._taint_strategy is None:
+            cfg_config = self._get_cfg_config()
+            if cfg_config.taint_strategy_factory is None:
+                raise ValueError(
+                    "CFGConfig has no taint_strategy_factory — "
+                    "LanguageBackend.cfg_config() must set one "
+                    "(see lang/python/cfg.py::default_python_cfg_config)."
+                )
+            self._taint_strategy = cfg_config.taint_strategy_factory(cfg_config)
+        return self._taint_strategy
+
+    def add_file_result(self, result: AnalysisResult) -> None:
+        """Add symbols and patterns from a single file to the graph."""
+        self.backend_names.add(result.language)
+        self.indexed_extensions.add(Path(result.file_path).suffix)
+        module_name = self._module_for_result(result)
+
+        # Add module node
+        module_id = f"{module_name}"
+        self._module_owners.setdefault(module_id, set()).add(str(result.file_path))
+        existing_mod = self._nodes.get(module_id)
+        if existing_mod is None:
+            module_node = GraphNode(
+                id=module_id,
+                name=self._display_module(module_name),
+                node_type=NodeType.MODULE,
+                module=module_name,
+                file_path=str(result.file_path),
+                line=0,
+                column=0,
+                language=result.language,
+            )
+            self._add_node(module_node)
+        elif existing_mod.node_type != NodeType.MODULE:
+            # P1.10 step 1: a non-module node already owns this id (e.g. class
+            # ``b`` in ``a/__init__.py`` vs submodule ``a/b.py``). The module
+            # node is the loser here (existing node kept) — record it.
+            logger.warning(
+                "node id collision: %r — MODULE (%s) blocked by existing %s (%s:%d)",
+                module_id, result.file_path,
+                existing_mod.node_type.name, existing_mod.file_path, existing_mod.line,
+            )
+            self.node_collisions[(str(result.file_path), 0)] = GraphNode(
+                id=module_id,
+                name=module_name,
+                node_type=NodeType.MODULE,
+                module=module_name,
+                file_path=str(result.file_path),
+                line=0,
+                column=0,
+            )
+
+        # Stash the resolved import map for later module-level IMPORTS edges
+        if result.imports or result.import_records:
+            self._pending_imports[str(result.file_path)] = (
+                module_id,
+                self._import_map_for(result, module_name),
+            )
+
+        # P1.11: map simple function name -> [(line, node_id)] for the symbols
+        # added in THIS call, so nested route handlers (registered inside a
+        # factory/setup method, e.g. @self.app.post(...) in _setup_routes) can
+        # be resolved by scope-aware id instead of the naive module:handler concat.
+        func_by_name: Dict[str, List[Tuple[int, str]]] = {}
+        # Java's `java_test` pattern (P4.3's JavaTestDetector) carries no
+        # function name in its metadata, only the position of the same
+        # `method_declaration` CST node the extractor itself positioned the
+        # Symbol on — so it's matched back to a node by exact line instead of
+        # by name (see the TESTS branch in the patterns loop below).
+        func_by_line: Dict[int, str] = {}
+
+        # Add symbols as nodes
+        for symbol in result.symbols:
+            node_id = self._symbol_to_id(symbol, module_name)
+            if symbol.kind == "class":
+                node_type = NodeType.CLASS
+            elif symbol.kind in ("variable", "attribute"):
+                node_type = NodeType.VARIABLE
+            else:
+                node_type = NodeType.FUNCTION
+                func_by_name.setdefault(symbol.name, []).append(
+                    (symbol.position.line, node_id)
+                )
+                func_by_line.setdefault(symbol.position.line, node_id)
+
+            graph_node = GraphNode(
+                id=node_id,
+                name=symbol.name,
+                node_type=node_type,
+                module=module_name,
+                file_path=str(symbol.file_path),
+                line=symbol.position.line,
+                column=symbol.position.column,
+                end_line=symbol.position.end_line,
+                is_async=symbol.is_async,
+                decorators=symbol.decorators,
+                docstring=symbol.docstring,
+                signature=symbol.signature,
+                contained_in=symbol.parent,
+                is_test=symbol.is_test,
+                metadata={
+                    **symbol.metadata,
+                    **({"modifiers": list(symbol.modifiers)} if symbol.modifiers else {}),
+                    **({"throws": list(symbol.throws)} if symbol.throws else {}),
+                },
+                language=result.language,
+            )
+
+            self._add_node(graph_node)
+
+            # Link to parent module
+            self._add_edge(GraphEdge(
+                source=module_id,
+                target=node_id,
+                edge_type=EdgeType.CONTAINS,
+                file_path=str(symbol.file_path),
+                line=symbol.position.line,
+            ))
+
+            # Link to immediate enclosing scope (class or function).
+            # P2.17: scope_chain encodes the full lexical scope outermost-first,
+            # so the immediate parent is module + all scope_chain segments.
+            # This ensures nested defs appear under their enclosing function
+            # (not just the module), enabling correct container expansion.
+            if symbol.scope_chain:
+                # P1.10: the chain embeds <locals> after function segments;
+                # the enclosing definition's own id has no trailing marker.
+                chain = symbol.scope_chain
+                if chain[-1] == LOCALS_MARKER:
+                    chain = chain[:-1]
+                parent_id = f"{module_name}:{'.'.join(chain)}"
+                self._add_edge(GraphEdge(
+                    source=parent_id,
+                    target=node_id,
+                    edge_type=EdgeType.CONTAINS,
+                ))
+            elif symbol.parent:
+                # Pre-P2.17 fallback for cached Symbol objects with no scope_chain
+                parent_id = f"{module_name}:{symbol.parent}"
+                self._add_edge(GraphEdge(
+                    source=parent_id,
+                    target=node_id,
+                    edge_type=EdgeType.CONTAINS,
+                ))
+
+            # Stash class superclasses for INHERITS resolution
+            if symbol.kind == "class" and symbol.superclasses:
+                self._pending_inherits[node_id] = (
+                    list(symbol.superclasses),
+                    str(symbol.file_path),
+                    symbol.position.line,
+                )
+            if symbol.kind == "class" and symbol.implements:
+                self._pending_implements[node_id] = (
+                    list(symbol.implements),
+                    str(symbol.file_path),
+                    symbol.position.line,
+                )
+
+            # Stash decorators for DECORATED_BY resolution
+            if symbol.decorators:
+                self._pending_decorators[node_id] = (
+                    list(symbol.decorators),
+                    module_name,
+                    str(symbol.file_path),
+                    symbol.position.line,
+                )
+
+        # Add patterns as hints for entry points
+        for pattern in result.patterns:
+            if pattern.category.name == "ROUTES":
+                # Route handlers are entry points
+                handler = pattern.metadata.get("handler", "")
+                if not handler:
+                    continue
+                # P1.11: resolve the handler against this file's FUNCTION nodes
+                # (scope-aware ids), so handlers nested in a factory/setup method
+                # are marked. Disambiguate same-named handlers by the candidate
+                # whose def line is closest at-or-after the pattern line (the
+                # decorator sits directly above the def). Fall back to the naive
+                # module:handler concat for cached results with no node match.
+                candidates = func_by_name.get(handler)
+                node_id = None
+                if candidates:
+                    pat_line = pattern.position.line
+                    at_or_after = [c for c in candidates if c[0] >= pat_line]
+                    chosen = min(at_or_after or candidates, key=lambda c: abs(c[0] - pat_line))
+                    node_id = chosen[1]
+                else:
+                    fallback = f"{module_name}:{handler}"
+                    if fallback in self._nodes:
+                        node_id = fallback
+                if node_id and node_id in self._nodes:
+                    self._nodes[node_id].is_entry_point = True
+                    self.graph.nodes[node_id]["is_entry_point"] = True
+            elif pattern.name == "java_test":
+                # Java's own `Symbol.is_test` is deliberately left unset by
+                # the extractor (PROBLEMS.md P4.2) — JUnit/TestNG detection
+                # is P4.3's `JavaTestDetector` job, so the flag is backfilled
+                # here from its `java_test` pattern the same way a ROUTES
+                # pattern backfills `is_entry_point` above. The pattern and
+                # the Symbol are positioned on the very same
+                # `method_declaration` node, so an exact line match (not the
+                # ROUTES branch's nearest-line heuristic) is enough.
+                node_id = func_by_line.get(pattern.position.line)
+                if node_id and node_id in self._nodes:
+                    self._nodes[node_id].is_test = True
+                    self.graph.nodes[node_id]["is_test"] = True
+
+    def _add_node(self, node: GraphNode) -> None:
+        """Add a node to the graph.
+
+        P1.10 step 1 (collision tripwire): same id arriving from a different
+        file means two distinct program entities share one id (e.g. namespace
+        package roots). Same-file type changes are normal Python rebinding, so
+        insertion stays last-write-wins without a false collision warning.
+        """
+        existing = self._nodes.get(node.id)
+        self._qualified_lookup_cache.clear()
+        self._global_dotted_index = None
+        self._class_by_simple_name_index = None
+        self._classes_by_simple_name = {}
+        if node.node_type == NodeType.MODULE:
+            self._module_suffix_index = None
+        if existing is not None and existing.file_path != node.file_path:
+            logger.warning(
+                "node id collision: %r — %s (%s:%d) overwrites %s (%s:%d)",
+                node.id,
+                node.node_type.name, node.file_path, node.line,
+                existing.node_type.name, existing.file_path, existing.line,
+            )
+            self.node_collisions[(existing.file_path, existing.line)] = existing
+        self._nodes[node.id] = node
+        self.graph.add_node(
+            node.id,
+            **node.to_dict()
+        )
+
+    def _add_edge(self, edge: GraphEdge) -> None:
+        """Add an edge to the graph.
+
+        Skip if an edge with same (source, target, edge_type) already exists.
+        Python permits duplicate method names within a class (later overrides
+        earlier); extractor emits a symbol per definition, so without this
+        guard duplicate CONTAINS edges leak through and violate the SQLite
+        UNIQUE constraint on save_graph.
+        """
+        key = (edge.source, edge.target, edge.edge_type)
+        if key in self._edge_keys:
+            return
+        self._edge_keys.add(key)
+        self._edges.append(edge)
+        self.graph.add_edge(
+            edge.source,
+            edge.target,
+            key=edge.edge_type.name,
+            **edge.to_dict()
+        )
+
+    def _record_edge_occurrence(self, edge: GraphEdge) -> None:
+        """Record one deterministic source occurrence without changing the
+        node-level dependency graph.
+
+        Exact byte ranges distinguish nested calls sharing a begin position.
+        Legacy producers without ranges fall back to line/column; identical
+        fallback records are conservatively deduplicated.
+        """
+        key = (
+            edge.source, edge.target, edge.edge_type, edge.file_path,
+            edge.start_byte if edge.start_byte is not None else edge.line,
+            edge.end_byte if edge.end_byte is not None else edge.column,
+        )
+        if key in self._occurrence_keys:
+            return
+        self._occurrence_keys.add(key)
+        self._edge_occurrences.append(edge)
+
+    def reconcile_edges(self) -> None:
+        """Drop edges whose endpoints no longer exist and re-sync the NetworkX
+        graph.  Called after an incremental update to clean up cross-file
+        edges whose target node was deleted or renamed in a changed file, and
+        to re-insert kept inbound edges whose target node was re-added.
+        """
+        kept: List[GraphEdge] = []
+        self._edge_keys.clear()
+        for e in self._edges:
+            if e.source not in self._nodes or e.target not in self._nodes:
+                continue
+            key = (e.source, e.target, e.edge_type)
+            if key in self._edge_keys:
+                continue
+            self._edge_keys.add(key)
+            kept.append(e)
+            if not self.graph.has_edge(e.source, e.target, key=e.edge_type.name):
+                self.graph.add_edge(
+                    e.source, e.target, key=e.edge_type.name, **e.to_dict()
+                )
+        self._edges = kept
+        self._edge_occurrences = [
+            e for e in self._edge_occurrences
+            if e.source in self._nodes and e.target in self._nodes
+        ]
+        self._occurrence_keys = {
+            (
+                e.source, e.target, e.edge_type, e.file_path,
+                e.start_byte if e.start_byte is not None else e.line,
+                e.end_byte if e.end_byte is not None else e.column,
+            )
+            for e in self._edge_occurrences
+        }
+
+    def remove_file(self, file_path: str) -> None:
+        """Remove all nodes and edges associated with a given file path.
+
+        Used during incremental updates when a file has changed or been deleted.
+        """
+        # P1.10: drop collision records anchored in the removed file — the
+        # displaced definition no longer exists in the source.
+        for key in list(self.node_collisions):
+            if key[0] == file_path:
+                del self.node_collisions[key]
+
+        # A Java package node is shared by every compilation unit in that
+        # package, including units that emit no symbols (package-info.java).
+        for module_id, owners in list(self._module_owners.items()):
+            if file_path not in owners:
+                continue
+            owners.remove(file_path)
+            if not owners:
+                del self._module_owners[module_id]
+                continue
+            module_node = self._nodes.get(module_id)
+            if module_node is not None and module_node.file_path == file_path:
+                module_node.file_path = min(owners)
+                self.graph.nodes[module_id]["file"] = module_node.file_path
+
+        nodes_to_remove = [nid for nid, node in self._nodes.items() if node.file_path == file_path]
+        nodes_set = set(nodes_to_remove)
+
+        # Clean up calls / called_by references on remaining nodes
+        for node in self._nodes.values():
+            node.calls -= nodes_set
+            node.called_by -= nodes_set
+
+        # Remove from NetworkX graph (this also removes incident edges)
+        for nid in nodes_to_remove:
+            if nid in self.graph:
+                self.graph.remove_node(nid)
+            del self._nodes[nid]
+        self._module_suffix_index = None
+        self._qualified_lookup_cache.clear()
+
+        # Drop outbound edges from removed nodes (their bodies are gone, so
+        # call resolution will re-emit them).  Keep inbound edges in the list
+        # so that callers in unchanged files don't lose their CALLS targets
+        # when the file is later re-added with the same symbol IDs.  These
+        # inbound edges get re-validated by ``reconcile_edges`` after the
+        # incremental update completes.
+        kept: List[GraphEdge] = []
+        for e in self._edges:
+            if e.source in nodes_set or e.file_path == file_path:
+                self._edge_keys.discard((e.source, e.target, e.edge_type))
+            else:
+                kept.append(e)
+        self._edges = kept
+        self._edge_occurrences = [
+            e for e in self._edge_occurrences
+            if e.source not in nodes_set and e.file_path != file_path
+        ]
+        self._occurrence_keys = {
+            (
+                e.source, e.target, e.edge_type, e.file_path,
+                e.start_byte if e.start_byte is not None else e.line,
+                e.end_byte if e.end_byte is not None else e.column,
+            )
+            for e in self._edge_occurrences
+        }
+
+        # Purge pending relationship data for removed nodes
+        for nid in list(self._pending_inherits):
+            if nid in nodes_set:
+                del self._pending_inherits[nid]
+        for nid in list(self._pending_implements):
+            if nid in nodes_set:
+                del self._pending_implements[nid]
+        for nid in list(self._pending_decorators):
+            if nid in nodes_set:
+                del self._pending_decorators[nid]
+        self._pending_imports.pop(file_path, None)
+        for nid in nodes_set:
+            self._decorator_rebirds.pop(nid, None)
+
+    def resolve_calls(
+        self,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+    ) -> int:
+        """Second pass: emit CALLS/INSTANTIATES/AWAITS/REFERENCES edges by
+        walking each function body — delegated to the active language's
+        `CallResolver` (P4.4). See `lang/python/resolver.py::
+        PythonCallResolver.resolve_calls` / `lang/java/resolver.py::
+        JavaCallResolver.resolve_calls` for the language-specific walk;
+        graph mechanics (edge dedupe, MultiDiGraph, confidence) stay here.
+        """
+        return self._get_resolver().resolve_calls(parses, results)
+
+    def resolve_relationships(self, results: Dict[Path, AnalysisResult]) -> int:
+        """Emit hierarchy, decorator, type, and module import edges.
+
+        Run after all files have been added via ``add_file_result``. Uses the
+        pending relationship data captured during file insertion.
+
+        Returns the number of edges added.
+        """
+        added = 0
+
+        # Indices over current graph state
+        by_simple_name: Dict[str, List[str]] = defaultdict(list)
+        by_module_symbol: Dict[str, Dict[str, str]] = defaultdict(dict)
+        for nid, node in self._nodes.items():
+            if node.node_type in (NodeType.FUNCTION, NodeType.CLASS):
+                by_simple_name[node.name].append(nid)
+                by_module_symbol[node.module][node.name] = nid
+
+        # Per-file import maps from the original file results (lets us resolve
+        # decorators like @app.route where `app` is an imported module/object).
+        import_maps_by_file: Dict[str, Dict[str, str]] = {}
+        for ar in results.values():
+            mod = self._module_for_result(ar)
+            import_maps_by_file[str(ar.file_path)] = self._import_map_for(ar, mod)
+
+        # ---- INHERITS / IMPLEMENTS ----
+        for pending, edge_type in (
+            (self._pending_inherits, EdgeType.INHERITS),
+            (self._pending_implements, EdgeType.IMPLEMENTS),
+        ):
+            for class_id, (parents, file_path, line) in pending.items():
+                if class_id not in self._nodes:
+                    continue
+                class_module = self._nodes[class_id].module
+                imap = import_maps_by_file.get(file_path, {})
+                for parent_name in parents:
+                    tid = self._resolve_name(
+                        parent_name, class_module, imap, by_simple_name, by_module_symbol,
+                        strict=True,
+                    )
+                    if (
+                        not tid
+                        or tid == class_id
+                        or self._has_edge_of_type(class_id, tid, edge_type)
+                    ):
+                        continue
+                    self._add_edge(GraphEdge(
+                        source=class_id,
+                        target=tid,
+                        edge_type=edge_type,
+                        file_path=file_path,
+                        line=line,
+                    ))
+                    added += 1
+
+        # ---- DECORATED_BY ----
+        for sym_id, (decorators, module_name, file_path, line) in self._pending_decorators.items():
+            if sym_id not in self._nodes:
+                continue
+            imap = import_maps_by_file.get(file_path, {})
+            for deco in decorators:
+                dname = self._decorator_name(deco)
+                if not dname:
+                    continue
+                head = dname.split(".")[0]
+                if head in ("self", "cls"):
+                    # method-bound decorator (e.g. @self.app.get) — receiver
+                    # type is unknown, skip rather than guess.
+                    continue
+                # Strict mode for decorators: only resolve via imports or same
+                # module. Simple-name fallback is too noisy here.
+                tid = self._resolve_name(
+                    dname, module_name, imap, by_simple_name, by_module_symbol,
+                    strict=True,
+                )
+                if not tid or tid == sym_id:
+                    continue
+                if self._has_edge_of_type(sym_id, tid, EdgeType.DECORATED_BY):
+                    continue
+                self._add_edge(GraphEdge(
+                    source=sym_id,
+                    target=tid,
+                    edge_type=EdgeType.DECORATED_BY,
+                    file_path=file_path,
+                    line=line,
+                ))
+                added += 1
+
+        # ---- TYPE_OF / RETURNS (P1.8) ----
+        # def f(svc: UserService) -> Report  →  f --TYPE_OF--> UserService,
+        # f --RETURNS--> Report. Strict annotation resolution only.
+        for ar in results.values():
+            mod = self._module_for_result(ar)
+            imap = import_maps_by_file.get(str(ar.file_path), {})
+            for sym in ar.symbols:
+                if sym.kind != "function":
+                    continue
+                fid = self._symbol_to_id(sym, mod)
+                if fid not in self._nodes:
+                    continue
+                for ann in sym.param_types.values():
+                    tid = self._resolve_annotation(
+                        ann, mod, imap, by_simple_name, by_module_symbol
+                    )
+                    if not tid or tid == fid:
+                        continue
+                    if (fid, tid, EdgeType.TYPE_OF) in self._edge_keys:
+                        continue
+                    self._add_edge(GraphEdge(
+                        source=fid,
+                        target=tid,
+                        edge_type=EdgeType.TYPE_OF,
+                        file_path=str(sym.file_path),
+                        line=sym.position.line,
+                    ))
+                    added += 1
+                if sym.return_type:
+                    tid = self._resolve_annotation(
+                        sym.return_type, mod, imap, by_simple_name, by_module_symbol
+                    )
+                    if tid and tid != fid and \
+                       (fid, tid, EdgeType.RETURNS) not in self._edge_keys:
+                        self._add_edge(GraphEdge(
+                            source=fid,
+                            target=tid,
+                            edge_type=EdgeType.RETURNS,
+                            file_path=str(sym.file_path),
+                            line=sym.position.line,
+                        ))
+                        added += 1
+
+        # ---- IMPORTS (module -> module) ----
+        module_by_suffix = self._module_suffixes()
+        for file_path, (module_id, imap) in self._pending_imports.items():
+            target_modules: Set[str] = set()
+            namespace = self._module_namespace(module_id)
+            prefix = f"{namespace}::" if namespace else ""
+            for local, dotted in imap.items():
+                # dotted is either a module ("a.b") or "module.symbol".
+                # Try the whole dotted path as a module first, then drop the
+                # last segment.
+                candidate = f"{prefix}{dotted}"
+                if candidate in self._nodes and self._nodes[candidate].node_type == NodeType.MODULE:
+                    target_modules.add(candidate)
+                    continue
+                parent = ".".join(dotted.split(".")[:-1])
+                parent_candidate = f"{prefix}{parent}"
+                if parent and parent_candidate in self._nodes and self._nodes[parent_candidate].node_type == NodeType.MODULE:
+                    target_modules.add(parent_candidate)
+                else:
+                    matched = module_by_suffix.get((namespace, dotted))
+                    if matched:
+                        target_modules.add(matched)
+            for tid in target_modules:
+                if tid == module_id:
+                    continue
+                if self._has_edge_of_type(module_id, tid, EdgeType.IMPORTS):
+                    continue
+                self._add_edge(GraphEdge(
+                    source=module_id,
+                    target=tid,
+                    edge_type=EdgeType.IMPORTS,
+                    file_path=file_path,
+                ))
+                added += 1
+
+        added += self._resolve_overrides()
+
+        return added
+
+    def _resolve_overrides(self) -> int:
+        """P2.8: derive OVERRIDES edges from INHERITS/IMPLEMENTS + CONTAINS.
+
+        For each INHERITS or IMPLEMENTS edge, intersect direct method
+        signatures of child and parent type; emit
+        ``child.method --OVERRIDES--> parent.method``.  Interface contracts
+        need the same dependency edge as inherited abstract methods: changing
+        a contract must reach callers of its concrete implementation.
+        Pure graph derivation (no extraction data), so it is safe to recompute
+        on every resolve pass — dedupe via ``_edge_keys``.
+
+        Only *declared* methods take part. Java's synthetic members (enum
+        ``values``/``valueOf``, record component accessors) are materialised
+        later by ``resolve_calls`` and persisted with the graph, so a fresh
+        build never sees them here while an incremental update on a loaded
+        graph would — and would emit OVERRIDES edges a full rebuild does not
+        (MCP_INCREMENTAL_REBUILD_PLAN.md Decision #7, Spring Modulith:
+        ``record JavaSourceChange(...) implements SourceChange``). Skipping
+        them keeps the derivation independent of build history.
+        """
+        added = 0
+
+        def _methods_of(class_id: str) -> Dict[str, str]:
+            out: Dict[str, str] = {}
+            if class_id not in self.graph:
+                return out
+            for _, child, d in self.graph.out_edges(class_id, data=True):
+                if d.get("type") != EdgeType.CONTAINS.name:
+                    continue
+                node = self._nodes.get(child)
+                if node is None or node.node_type != NodeType.FUNCTION:
+                    continue
+                if node.metadata.get("java_synthetic_record_accessor") or node.metadata.get(
+                    "java_synthetic_enum_method"
+                ):
+                    continue
+                # Java overloads share `node.name`; the opaque id retains
+                # the erased signature and is therefore the stable key.
+                out[child.rsplit(".", 1)[-1]] = child
+            return out
+
+        for edge in list(self._edges):
+            if edge.edge_type not in (EdgeType.INHERITS, EdgeType.IMPLEMENTS):
+                continue
+            child_methods = _methods_of(edge.source)
+            if not child_methods:
+                continue
+            parent_methods = _methods_of(edge.target)
+            for name in child_methods.keys() & parent_methods.keys():
+                src, tgt = child_methods[name], parent_methods[name]
+                if (src, tgt, EdgeType.OVERRIDES) in self._edge_keys:
+                    continue
+                src_node = self._nodes[src]
+                self._add_edge(GraphEdge(
+                    source=src,
+                    target=tgt,
+                    edge_type=EdgeType.OVERRIDES,
+                    file_path=src_node.file_path,
+                    line=src_node.line,
+                ))
+                added += 1
+        return added
+
+    def _has_edge_of_type(self, src: str, tgt: str, etype: EdgeType) -> bool:
+        return (src, tgt, etype) in self._edge_keys
+
+    # ------------------------------------------------------------------ P2.15
+
+    def resolve_decorator_types(
+        self,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+    ) -> None:
+        """Optional decorator/annotation-stub pre-pass — delegated to the
+        active language's `CallResolver` (P4.4). Python's P2.15 stub table +
+        narrow own-inference lives in `lang/python/resolver.py::
+        PythonCallResolver.resolve_decorator_types`; Java's simpler
+        annotation-stub lookup resolves inline in `_resolve_target` and
+        leaves this a no-op (`CallResolver`'s default)."""
+        self._get_resolver().resolve_decorator_types(parses, results)
+
+    def _resolve_name(
+        self,
+        name: str,
+        module_name: str,
+        import_map: Dict[str, str],
+        by_simple_name: Dict[str, List[str]],
+        by_module_symbol: Dict[str, Dict[str, str]],
+        strict: bool = False,
+    ) -> Optional[str]:
+        """Resolve a (possibly dotted) name to a graph node id.
+
+        ``strict=True`` skips the simple-name fallback (used by DECORATED_BY
+        and INHERITS where over-approximation produces noisy false positives).
+        """
+        if not name:
+            return None
+        namespace = self._module_namespace(module_name)
+        if "." in name:
+            head, *_, tail = name.split(".")
+            if head in import_map:
+                resolved = import_map[head]
+                tid = self._lookup_qualified(
+                    f"{resolved}.{tail}", by_module_symbol, namespace
+                )
+                if tid:
+                    return tid
+            # try last segment in same module
+            if tail in by_module_symbol.get(module_name, {}):
+                return by_module_symbol[module_name][tail]
+            if strict:
+                return None
+            cands = by_simple_name.get(tail, [])
+            if len(cands) == 1:
+                return cands[0]
+            return None
+        # bare identifier
+        if name in by_module_symbol.get(module_name, {}):
+            return by_module_symbol[module_name][name]
+        if name in import_map:
+            resolved = import_map[name]
+            tid = self._lookup_qualified(resolved, by_module_symbol, namespace)
+            if tid:
+                return tid
+            # The whole dotted path may itself be a function/class/module —
+            # boundary unknown, try the ':' splits (P1.10 step 4).
+            tid = self._node_for_dotted(resolved, namespace)
+            if tid:
+                return tid
+        if strict:
+            return None
+        cands = by_simple_name.get(name, [])
+        if len(cands) == 1:
+            return cands[0]
+        return None
+
+    @staticmethod
+    def _decorator_name(deco: str) -> Optional[str]:
+        """Extract the callable name from a decorator string (e.g. '@app.route(\"/\")' -> 'app.route')."""
+        s = deco.strip()
+        if s.startswith("@"):
+            s = s[1:].lstrip()
+        # cut at first '(' to drop arguments
+        paren = s.find("(")
+        if paren >= 0:
+            s = s[:paren]
+        s = s.strip()
+        # only allow dotted identifier chars
+        return s if s and all(c.isalnum() or c in "._" for c in s) else None
+
+    @classmethod
+    def from_results(
+        cls,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+        project_root: Optional[Path] = None,
+        resolver_config: Optional[ResolverConfig] = None,
+        cfg_config: Optional[CFGConfig] = None,
+    ) -> "CallGraphBuilder":
+        """Convenience: build full graph (CONTAINS + CALLS) in one shot.
+
+        `resolver_config` is None by default (Python, via `_get_resolver()`'s
+        lazy fallback) — pass a Java backend's `resolver_config()` to build a
+        Java graph the same way (P4.4). `cfg_config` is the P4.6 analogue,
+        consumed by `TaintAnalyzer`/`graph.cfg.analyze_function` rather than
+        by anything in this method."""
+        builder = cls(
+            project_root=project_root,
+            resolver_config=resolver_config,
+            cfg_config=cfg_config,
+        )
+        for r in results.values():
+            builder.add_file_result(r)
+        builder.resolve_relationships(results)
+        builder.resolve_decorator_types(parses, results)
+        builder.resolve_calls(parses, results)
+        builder.harvest_literal_candidates(parses, results)
+        return builder
+
+    # ---- impact analysis ----
+
+    def get_entry_points(self) -> List[GraphNode]:
+        """Get all graph entry points (route handlers, main functions)."""
+        return [n for n in self._nodes.values() if n.is_entry_point]
+
+    def get_dependencies(self, node_id: str) -> List[str]:
+        """Transitive callees (what `node_id` depends on) via CALLS and
+        INSTANTIATES edges.
+
+        Container expansion (P2.10, mirror of P1.6's incoming fix): a class
+        or module depends on whatever its members call — members are seeded
+        at depth 0 and excluded from the result, exactly like
+        ``get_transitive_callers`` on the incoming side.
+        """
+        if node_id not in self.graph:
+            return []
+        seeds = [node_id] + self.get_container_members(node_id)
+        seen: Set[str] = set(seeds)
+        out: List[str] = []
+        q: deque[str] = deque(seeds)
+        while q:
+            cur = q.popleft()
+            for _, b, d in self.graph.out_edges(cur, data=True):
+                if d.get("type") not in (
+                    EdgeType.CALLS.name, EdgeType.CALLABLE_REF.name,
+                    EdgeType.INSTANTIATES.name,
+                ):
+                    continue
+                if b in seen:
+                    continue
+                seen.add(b)
+                out.append(b)
+                q.append(b)
+        return out
+
+    # Incoming edge kinds that mean "the source depends on the target" for
+    # blast-radius purposes (P1.8/P2.8): calls, variable reads, type
+    # annotations, instantiation, overriding, interface implementation.
+    # CONTAINS is deliberately excluded (container expansion handles it).
+    IMPACT_EDGE_TYPES = frozenset({
+        EdgeType.CALLS.name,
+        EdgeType.CALLABLE_REF.name,
+        EdgeType.REFERENCES.name,
+        EdgeType.TYPE_OF.name,
+        EdgeType.RETURNS.name,
+        EdgeType.INSTANTIATES.name,
+        EdgeType.OVERRIDES.name,
+        EdgeType.IMPLEMENTS.name,
+        EdgeType.DYNAMIC_ATTR.name,  # P2.14: __getattr__ class reads
+    })
+
+    # Bugfix (2026-09-08): subset of IMPACT_EDGE_TYPES that reflects an
+    # actual call/reference site, minus OVERRIDES. An OVERRIDES edge means
+    # "this class re-implements that member's signature" — a structural
+    # fact derived from INHERITS/IMPLEMENTS (_resolve_overrides), not a call
+    # site. Every INHERITS/IMPLEMENTS edge whose two classes share a method
+    # name produces one, so a base method with N real implementors always
+    # has >= N OVERRIDES edges pointing at it, drowning out its actual
+    # callers in get_impact_analysis's `direct_callers` (misread as "who
+    # calls this" by any consumer, human or agent, going only by the field
+    # name/docs) and pushing them one hop further out as
+    # `transitive_callers`. Used only for that "direct" computation —
+    # get_callers()/walk_callers()/get_transitive_callers() keep the full
+    # IMPACT_EDGE_TYPES (OVERRIDES included) since the deeper
+    # polymorphic-dispatch signal ("callers of the base may execute the
+    # override", drift.md) is still correct and intentional there.
+    DIRECT_CALLER_EDGE_TYPES = IMPACT_EDGE_TYPES - {EdgeType.OVERRIDES.name}
+    INITIALIZER_SYNTHETIC_KINDS = frozenset({
+        "class_initializer", "instance_initializer",
+    })
+
+    def _is_initializer_node(self, node_id: str) -> bool:
+        """Whether ``node_id`` represents Java's synthetic init context.
+
+        Initializers remain real graph nodes and dependency-edge sources.  The
+        distinction is presentation semantics: they are executable contexts,
+        but not source-declared methods or constructors and therefore should
+        not silently inflate an impact report's caller counts.
+        """
+        node = self._nodes.get(node_id)
+        return bool(
+            node is not None
+            and node.metadata.get("synthetic") in self.INITIALIZER_SYNTHETIC_KINDS
+        )
+
+    def _declaring_class_id(self, member_id: str) -> Optional[str]:
+        """The fully-qualified id of `member_id`'s immediate declaring
+        class, via the reverse CONTAINS edge wired from `Symbol.scope_chain`
+        (`f"{module}:{'.'.join(chain)}"`) when the node was added.
+
+        Unlike `GraphNode.contained_in` — which both language extractors'
+        own `_find_parent_class` deliberately keep as the coarser *nearest
+        enclosing simple name* ("Box"), a separate, coarser field than the
+        scope-chain uniqueness key — this is qualified even for a nested
+        class ("Outer.Box"), matching the id the class's own CONTAINS
+        source actually has. A bare `f"{module}:{contained_in}"` lookup
+        silently misses for any nested class member, in either language."""
+        if member_id not in self.graph:
+            return None
+        for source, _, data in self.graph.in_edges(member_id, data=True):
+            if data.get("type") != EdgeType.CONTAINS.name:
+                continue
+            source_node = self._nodes.get(source)
+            if source_node is not None and source_node.node_type == NodeType.CLASS:
+                return source
+        return None
+
+    def _impact_in_edges(
+        self, node_id: str, edge_types: Optional[frozenset] = None
+    ) -> List[Tuple[str, str, float]]:
+        """Incoming dependents of `node_id` over `edge_types` (default
+        IMPACT_EDGE_TYPES), as ``(source_id, edge_type_name, confidence)``
+        triples.
+
+        P2.8: when `node_id` is a constructor (Python's `__init__`, or a
+        Java constructor — `symbol.metadata["constructor"]`, since Java
+        names a constructor after its class, never `__init__`), INSTANTIATES
+        edges point at its *class* node — fold those sources in so
+        constructor blast radius includes every `Foo()` / `new Foo()` site.
+        """
+        if edge_types is None:
+            edge_types = self.IMPACT_EDGE_TYPES
+        out = [
+            (u, d.get("type"), float(d.get("confidence", 1.0)))
+            for u, _, d in self.graph.in_edges(node_id, data=True)
+            if d.get("type") in edge_types
+        ]
+        node = self._nodes.get(node_id)
+        is_constructor = node is not None and (
+            node.name == "__init__" or node.metadata.get("constructor")
+        )
+        # Bugfix (2026-09-11): only fold in a constructor's INSTANTIATES
+        # sources when the caller actually asked for that edge type. Before
+        # this check, the fold fired unconditionally, so `_override_family`'s
+        # OVERRIDES-only probe (`edge_types={OVERRIDES.name}`) on a
+        # constructor picked up every `new Foo(...)` call site as a bogus
+        # "override family member" — then `_direct_callers` walked *those*
+        # members' own callers one hop further, mislabeling depth-2 callers
+        # (a factory-method forwarder, helper-method callers in tests) as
+        # depth-1 direct callers of the constructor.
+        if is_constructor and EdgeType.INSTANTIATES.name in edge_types:
+            class_id = self._declaring_class_id(node_id)
+            if class_id is not None and class_id in self.graph:
+                # Bugfix (2026-09-12): a class with more than one declared
+                # constructor still has exactly one INSTANTIATES target (the
+                # class node — `_resolve_constructor`'s own docstring: "never
+                # fans out to per-constructor targets"), so every `new Foo(...)`
+                # site's edge lands here regardless of which overload it
+                # actually resolved to. Without this filter, querying *any one*
+                # overload's callers returned the union of every overload's
+                # callers (spring-modulith benchmark: `ShiftedQuarter.of`'s and
+                # `ApplicationModules.of(Class)`'s both-previously-unreconciled
+                # +6 full-depth overcounts — `MomentsProperties`'s and
+                # `Documenter`'s *other* same-arity constructor, which takes an
+                # already-built value instead of deriving one, got folded in
+                # too, then walked one hop further transitively). Each edge's
+                # own `constructor_signature` (set by `_resolve_constructor`
+                # whenever a single overload was actually selected) is the
+                # erased suffix embedded in every constructor node id
+                # (`Foo.(Bar,int)`) — compare the two; a missing/`None` value
+                # means resolution itself was ambiguous between constructors,
+                # so keep including it rather than manufacture a false
+                # exclusion.
+                own_signature = node_id[node_id.rfind("("):] if "(" in node_id else None
+                out.extend(
+                    (u, d.get("type"), float(d.get("confidence", 1.0)))
+                    for u, _, d in self.graph.in_edges(class_id, data=True)
+                    if d.get("type") == EdgeType.INSTANTIATES.name
+                    and (
+                        own_signature is None
+                        or d.get("metadata", {}).get("constructor_signature") in (None, own_signature)
+                    )
+                )
+        return out
+
+    def _impact_in_neighbors(self, node_id: str) -> List[str]:
+        """Incoming dependent node ids of `node_id` over IMPACT_EDGE_TYPES."""
+        return [u for u, _, _ in self._impact_in_edges(node_id)]
+
+    def get_callers(self, node_id: str) -> List[str]:
+        """Direct dependents of `node_id`: callers, variable readers,
+        functions typed by it, instantiators, overriders, and implementors."""
+        if node_id not in self.graph:
+            return []
+        return list(dict.fromkeys(self._impact_in_neighbors(node_id)))
+
+    def _override_family(self, node_id: str) -> List[str]:
+        """`node_id` plus every node reachable by following incoming OVERRIDES
+        edges (i.e. `node_id` itself, its direct overriders, their own
+        overriders, ...). All members dispatch the same logical operation —
+        a call resolved to any one of them is a real invocation of the
+        others' contract too."""
+        family = [node_id]
+        seen = {node_id}
+        idx = 0
+        while idx < len(family):
+            cur = family[idx]
+            idx += 1
+            for u, _, _ in self._impact_in_edges(
+                cur, edge_types={EdgeType.OVERRIDES.name}
+            ):
+                if u not in seen:
+                    seen.add(u)
+                    family.append(u)
+        return family
+
+    def _direct_callers(self, node_id: str) -> List[str]:
+        """Real call/reference sites for `node_id` — `get_callers()` minus
+        OVERRIDES (DIRECT_CALLER_EDGE_TYPES), used for get_impact_analysis's
+        `direct_callers`, where an overrider is not itself a call site.
+
+        Bugfix (2026-09-08) follow-up: benchmarked against ground truth,
+        excluding OVERRIDES alone undercounts an interface/base method's
+        direct callers to 0 whenever every real call site was resolved (by
+        P4.12 dispatch fan-out) straight to a concrete implementation rather
+        than the interface node — e.g. `OwnerRepository.findById` in the
+        Spring PetClinic corpus: GT=2 real callers, this method previously
+        returned 0. Fixed by flattening one degree of dispatch: also fold in
+        the real callers of every node in `node_id`'s OVERRIDES family
+        (`_override_family`) — the overriders themselves stay excluded, only
+        *their* callers count. This is asymmetric by design — querying a
+        concrete override's own direct callers must NOT pull in the
+        interface's callers through *other*, unrelated implementations."""
+        if node_id not in self.graph:
+            return []
+        out: List[str] = []
+        seen: Set[str] = set()
+        for member in self._override_family(node_id):
+            for u, _, _ in self._impact_in_edges(
+                member, edge_types=self.DIRECT_CALLER_EDGE_TYPES
+            ):
+                if u not in seen:
+                    seen.add(u)
+                    out.append(u)
+        return out
+
+    # Node types whose members are "part of" the node for impact purposes
+    CONTAINER_TYPES = (NodeType.CLASS, NodeType.MODULE)
+
+    def get_container_members(self, node_id: str) -> List[str]:
+        """Transitive CONTAINS descendants of a container node (class/module).
+
+        Returns [] for non-container nodes. Changing a container implicitly
+        changes every member (P1.6 / CODEGRAPH_2.md §5.1).
+        """
+        node = self._nodes.get(node_id)
+        if node is None or node.node_type not in self.CONTAINER_TYPES:
+            return []
+        out: List[str] = []
+        seen: Set[str] = {node_id}
+        q: deque[str] = deque([node_id])
+        while q:
+            cur = q.popleft()
+            for _, child, d in self.graph.out_edges(cur, data=True):
+                if d.get("type") != EdgeType.CONTAINS.name or child in seen:
+                    continue
+                seen.add(child)
+                out.append(child)
+                q.append(child)
+        return out
+
+    def get_transitive_callers(self, node_id: str) -> Dict[str, int]:
+        """Reverse BFS over dependency edges (CALLS / REFERENCES / TYPE_OF /
+        RETURNS). Returns {node_id: depth}.
+
+        Container expansion (P1.6): when `node_id` is a class or module,
+        its CONTAINS descendants are seeded at depth 0 — their callers
+        therefore appear at depth 1, exactly as if the member itself had
+        changed. CONTAINS is never followed on the incoming side, so a
+        method's impact does not climb to its class and re-expand siblings.
+        Calls *between* members of the same container are not reported as
+        impact (both endpoints are seeds).
+        """
+        if node_id not in self.graph:
+            return {}
+        seeds = [node_id] + self.get_container_members(node_id)
+        depths: Dict[str, int] = {}
+        visited: Set[str] = set(seeds)
+        q: deque[Tuple[str, int]] = deque((s, 0) for s in seeds)
+        while q:
+            cur, depth = q.popleft()
+            for u in self._impact_in_neighbors(cur):
+                if u in visited:
+                    continue
+                visited.add(u)
+                depths[u] = depth + 1
+                q.append((u, depth + 1))
+        return depths
+
+    def get_transitive_instantiators(self, node_id: str) -> Dict[str, int]:
+        """Reverse BFS whose first hop is instantiation-only, then walks the
+        regular dependency graph outward from there. The transitive
+        counterpart of ``instantiator_count`` (get_impact_analysis).
+
+        ``get_transitive_callers(class_or_ctor)`` seeds every hop — including
+        the first, straight off the class/constructor node — with the full
+        IMPACT_EDGE_TYPES union (TYPE_OF/RETURNS/INSTANTIATES/OVERRIDES/...).
+        That answers "who transitively depends on this *type*", which is the
+        right question for "what breaks if I change this class's shape" but
+        not comparable to a ground truth that only counts callers reachable
+        by *constructing* the target (`Target(...)` / `new Target(...)` call
+        chains) — benchmarking transitive_callers against such a GT for a
+        class target silently compares two different questions (e.g. FastAPI
+        benchmark: `Dependant`'s transitive_callers was 60 against a
+        construction-chain GT of 42 — not a 18-node overcount, a category
+        mismatch).
+
+        This narrows hop 1 to the same INSTANTIATES-only sources as
+        ``instantiator_count`` (constructor-fold included, via
+        ``_impact_in_edges``); hop 2+ walk ``_impact_in_neighbors`` exactly
+        like ``get_transitive_callers``, since once you are past the actual
+        instantiation site the question reverts to ordinary "who calls this
+        function" reachability.
+        """
+        if node_id not in self.graph:
+            return {}
+        depths: Dict[str, int] = {}
+        visited: Set[str] = {node_id}
+        q: deque[Tuple[str, int]] = deque()
+        for member in self._override_family(node_id):
+            for u, _, _ in self._impact_in_edges(
+                member, edge_types=frozenset({EdgeType.INSTANTIATES.name})
+            ):
+                if u in visited:
+                    continue
+                visited.add(u)
+                depths[u] = 1
+                q.append((u, 1))
+        while q:
+            cur, depth = q.popleft()
+            for u in self._impact_in_neighbors(cur):
+                if u in visited:
+                    continue
+                visited.add(u)
+                depths[u] = depth + 1
+                q.append((u, depth + 1))
+        return depths
+
+    # Outgoing edge kinds that mean "the source depends on the target"
+    # (mirror of IMPACT_EDGE_TYPES for the forward direction).
+    DEPENDENCY_EDGE_TYPES = frozenset({
+        EdgeType.CALLS.name,
+        EdgeType.CALLABLE_REF.name,
+        EdgeType.INSTANTIATES.name,
+    })
+
+    def walk_callers(
+        self, node_id: str, max_depth: Optional[int] = 1
+    ) -> List[Dict[str, Any]]:
+        """P2.11: depth-annotated reverse BFS over IMPACT_EDGE_TYPES.
+
+        Returns ``[{id, depth, edge_type, confidence}]`` in BFS order
+        (depth ascending). Container members are seeded at depth 0 (P1.6)
+        and excluded from the result. ``max_depth=None`` is unbounded.
+        ``edge_type``/``confidence`` describe the edge that first reached
+        the node.
+        """
+        if node_id not in self.graph:
+            return []
+        seeds = [node_id] + self.get_container_members(node_id)
+        visited: Set[str] = set(seeds)
+        out: List[Dict[str, Any]] = []
+        q: deque[Tuple[str, int]] = deque((s, 0) for s in seeds)
+        while q:
+            cur, depth = q.popleft()
+            if max_depth is not None and depth >= max_depth:
+                continue
+            for u, etype, conf in self._impact_in_edges(cur):
+                if u in visited:
+                    continue
+                visited.add(u)
+                out.append({
+                    "id": u, "depth": depth + 1,
+                    "edge_type": etype, "confidence": conf,
+                    **self._edge_strategy(u, cur, etype),
+                })
+                q.append((u, depth + 1))
+        return out
+
+    def walk_callees(
+        self, node_id: str, max_depth: Optional[int] = 1
+    ) -> List[Dict[str, Any]]:
+        """P2.11: depth-annotated forward BFS over CALLS + INSTANTIATES.
+
+        Same contract as ``walk_callers`` (container members seeded at
+        depth 0 per P2.10, excluded from the result).
+        """
+        if node_id not in self.graph:
+            return []
+        seeds = [node_id] + self.get_container_members(node_id)
+        visited: Set[str] = set(seeds)
+        out: List[Dict[str, Any]] = []
+        q: deque[Tuple[str, int]] = deque((s, 0) for s in seeds)
+        while q:
+            cur, depth = q.popleft()
+            if max_depth is not None and depth >= max_depth:
+                continue
+            for _, b, d in self.graph.out_edges(cur, data=True):
+                if d.get("type") not in self.DEPENDENCY_EDGE_TYPES or b in visited:
+                    continue
+                visited.add(b)
+                out.append({
+                    "id": b, "depth": depth + 1,
+                    "edge_type": d.get("type"),
+                    "confidence": float(d.get("confidence", 1.0)),
+                    **self._edge_provenance(d),
+                })
+                q.append((b, depth + 1))
+        return out
+
+    def find_path(self, src: str, dst: str) -> Optional[Dict[str, Any]]:
+        """P2.11: shortest path from `src` to `dst`.
+
+        Tries the directed graph first, then falls back to undirected
+        (reporting which succeeded). Each hop carries the connecting
+        edge's type + confidence; ``reversed`` marks hops that only exist
+        against edge direction (undirected fallback). Returns None when
+        no path exists at all.
+        """
+        if src not in self.graph or dst not in self.graph:
+            return None
+        try:
+            nodes = nx.shortest_path(self.graph, src, dst)
+            direction = "directed"
+        except nx.NetworkXNoPath:
+            try:
+                nodes = nx.shortest_path(
+                    self.graph.to_undirected(as_view=True), src, dst
+                )
+                direction = "undirected"
+            except nx.NetworkXNoPath:
+                return None
+        steps: List[Dict[str, Any]] = []
+        for a, b in zip(nodes, nodes[1:]):
+            data = self.graph.get_edge_data(a, b)
+            reversed_hop = False
+            if data is None:
+                data = self.graph.get_edge_data(b, a) or {}
+                reversed_hop = True
+            best = max(
+                data.values(),
+                key=lambda d: float(d.get("confidence", 1.0)),
+            ) if data else {}
+            steps.append({
+                "id": a,
+                "edge_to_next": {
+                    "type": best.get("type"),
+                    "confidence": float(best.get("confidence", 1.0)),
+                    "reversed": reversed_hop,
+                    **self._edge_provenance(best),
+                },
+            })
+        steps.append({"id": nodes[-1], "edge_to_next": None})
+        return {"direction": direction, "path": steps, "length": len(nodes) - 1}
+
+    def alternate_paths(self, src: str, dst: str, k: int) -> List[Dict[str, Any]]:
+        """MCP_TOKEN_BUDGET_PLAN.md Lớp 3: up to ``k`` directed simple paths
+        after the shortest one, ids only, shortest first. Computed on a
+        DiGraph view (shortest_simple_paths rejects multigraphs) only when
+        a caller asks — the primary path never pays for this."""
+        if k <= 0 or src not in self.graph or dst not in self.graph:
+            return []
+        simple = nx.DiGraph(self.graph)
+        out: List[Dict[str, Any]] = []
+        try:
+            gen = nx.shortest_simple_paths(simple, src, dst)
+            next(gen)  # the primary path, already reported
+            for nodes in gen:
+                out.append({"path": list(nodes), "length": len(nodes) - 1})
+                if len(out) >= k:
+                    break
+        except (nx.NetworkXNoPath, nx.NodeNotFound, StopIteration):
+            return out
+        return out
+
+    def _edge_strategy(self, source: str, target: str, edge_type: str) -> Dict[str, str]:
+        data = self.graph.get_edge_data(source, target, key=edge_type) or {}
+        return self._edge_provenance(data)
+
+    @staticmethod
+    def _edge_provenance(data: Dict[str, Any]) -> Dict[str, str]:
+        """MCP_TOKEN_BUDGET_PLAN.md Lớp 2: the coarse ``strategy``
+        (``java_resolver``) plus the fine-grained ``metadata["strategy"]``
+        (``interface_fanout``, ``single_implementor``, ``spring_qualifier``,
+        ...) as ``resolution`` — the actual uncertainty signal for abstract
+        dispatch, which never reached MCP responses before."""
+        out: Dict[str, str] = {}
+        if data.get("strategy"):
+            out["strategy"] = data["strategy"]
+        meta = data.get("metadata")
+        if isinstance(meta, dict) and meta.get("strategy"):
+            out["resolution"] = str(meta["strategy"])
+        return out
+
+    def _distinct_impact_targets(self, matches: List[str]) -> List[str]:
+        """Collapse `find_nodes` matches down to distinct top-level impact
+        targets.
+
+        Bugfix: a container's own members (e.g. a Java constructor, whose
+        `GraphNode.name` is always its class's simple name per
+        `extractor.py`'s `metadata["constructor"]` convention) previously
+        counted as a *second*, unrelated ambiguous match alongside their own
+        class — `find_nodes("Box")`'s exact_name tier returns both the class
+        and its constructor node. Worse, when two genuinely distinct classes
+        share a simple name (e.g. two nested `Box` classes in different
+        outers), that inflates to 4 matches for 2 real entities, and
+        `get_impact_analysis` used to silently analyze only `matches[0]` —
+        one arbitrary class — reporting e.g. zero direct callers even when
+        the *other*, unpicked, identically-named class had real callers.
+        Filtering out matches that are already covered by another match's
+        `get_container_members()` collapses class+own-constructor pairs
+        into one target, leaving only genuinely separate entities (if any)
+        for `get_impact_analysis` to merge impact across."""
+        member_sets = {m: set(self.get_container_members(m)) for m in matches}
+        primaries = [
+            m for m in matches
+            if not any(m in member_sets[other] for other in matches if other != m)
+        ]
+        return primaries or list(matches)
+
+    # Characters that continue a dotted identifier segment (Java also uses
+    # `$` for synthetic/nested-class names). Used by `_boundary_contains` to
+    # reject a substring match that lands mid-identifier.
+    _IDENT_CONTINUE = frozenset(
+        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_$"
+    )
+
+    @classmethod
+    def _boundary_contains(cls, haystack: str, needle: str) -> bool:
+        """`needle in haystack`, but only accepts a match whose start is a
+        token boundary (string start, or preceded by a non-identifier
+        character like `.`/`:`/`(`/`,`).
+
+        Bugfix: the old plain `in` check let an unrelated, longer identifier
+        that merely ends with the query steal a match — e.g. a query for
+        class `ApplicationModules` also matched `TestApplicationModules`
+        (a distinct class), because `"ApplicationModules"` is a literal
+        substring of `"TestApplicationModules"`. Only the leading edge is
+        checked (not the trailing one) so prefix-style fuzzy search, e.g.
+        `getSpring` finding `getSpringBeans`, still works.
+        """
+        start = 0
+        while True:
+            idx = haystack.find(needle, start)
+            if idx == -1:
+                return False
+            if idx == 0 or haystack[idx - 1] not in cls._IDENT_CONTINUE:
+                return True
+            start = idx + 1
+
+    @staticmethod
+    def _split_signature_suffix(text: str) -> Tuple[str, Optional[str]]:
+        """Split `text` into `(base, raw_params)` if it ends with a `(...)`
+        suffix (e.g. a query written as ``Class.method(Param)`` or
+        ``Class(Param)`` for a constructor), else `(text, None)`."""
+        if not text.endswith(")"):
+            return text, None
+        idx = text.find("(")
+        if idx == -1:
+            return text, None
+        return text[:idx], text[idx + 1:-1]
+
+    @staticmethod
+    def _normalize_signature_param(text: str) -> str:
+        """Erase top-level generic type arguments and whitespace so a
+        query's ``Class<?>`` compares equal to a stored ``Class`` —
+        mirroring the erasure `lang.java.ids.erased_type` already applies
+        when a node id's `signature_key` is built, without this
+        language-agnostic module importing that Java-specific helper."""
+        out: List[str] = []
+        depth = 0
+        for ch in text.strip():
+            if ch == "<":
+                depth += 1
+            elif ch == ">":
+                depth = max(depth - 1, 0)
+            elif depth == 0:
+                out.append(ch)
+        return "".join("".join(out).split())
+
+    @classmethod
+    def _parse_signature_params(cls, raw_params: str) -> List[str]:
+        """Split a `(...)`-interior parameter-type list on top-level commas
+        (respecting nested `<...>` generics) and erase each one."""
+        if not raw_params.strip():
+            return []
+        parts: List[str] = []
+        depth = 0
+        current: List[str] = []
+        for ch in raw_params:
+            if ch == "<":
+                depth += 1
+                current.append(ch)
+            elif ch == ">":
+                depth -= 1
+                current.append(ch)
+            elif ch == "," and depth == 0:
+                parts.append("".join(current))
+                current = []
+            else:
+                current.append(ch)
+        parts.append("".join(current))
+        return [cls._normalize_signature_param(p) for p in parts]
+
+    @classmethod
+    def _node_signature_params(cls, node_id: str) -> Optional[List[str]]:
+        """The erased parameter-type list a Java overload's own node id
+        encodes (its trailing `(...)` `signature_key`), or None for a node
+        id with no such suffix (non-Java backends never append one)."""
+        if not node_id.endswith(")"):
+            return None
+        idx = node_id.rfind("(")
+        if idx == -1:
+            return None
+        return cls._parse_signature_params(node_id[idx + 1:-1])
+
+    def find_nodes(self, query: str) -> List[str]:
+        """Match nodes by id, qualified name, simple name, signature, or
+        substring.
+
+        P1.10 step 3: qualified_name is the search alias for the id — a dotted
+        query like ``m.Foo.bar`` keeps matching even when the underlying id
+        carries <locals> markers (and would survive any future id format
+        change).
+        """
+        direct = [nid for nid in self._nodes if nid == query or nid.endswith(f"::{query}")]
+        if direct:
+            return direct
+        exact_qual = [nid for nid, n in self._nodes.items() if n.qualified_name == query]
+        if exact_qual:
+            return exact_qual
+        exact_name = [nid for nid, n in self._nodes.items() if n.name == query]
+        if exact_name:
+            return exact_name
+
+        # Bugfix: a query written with a signature suffix (e.g.
+        # ``FormattableType.of(Class<?>)``, copied straight from the Java
+        # source/Javadoc) used to only "match" by literal-text accident —
+        # it broke on generics, extra whitespace, or a fully-qualified
+        # param type, since `GraphNode.qualified_name` strips every `(...)`
+        # and no tier above ever parsed the signature at all. Disambiguate
+        # by erased param types when the query has a `(...)` suffix, before
+        # falling back to plain substring.
+        base, raw_params = self._split_signature_suffix(query)
+        if raw_params is not None and base:
+            query_params = self._parse_signature_params(raw_params)
+            sig_matches = [
+                nid for nid, n in self._nodes.items()
+                if (self._boundary_contains(nid, base) or self._boundary_contains(n.qualified_name, base))
+                and self._node_signature_params(nid) == query_params
+            ]
+            if sig_matches:
+                return sig_matches
+
+        return [
+            nid for nid, n in self._nodes.items()
+            if self._boundary_contains(nid, query) or self._boundary_contains(n.qualified_name, query)
+        ]
+
+    def get_impact_analysis(
+        self, query: str, *, include_initializers: bool = False,
+    ) -> Dict[str, Any]:
+        """Blast-radius report for `query` (qualified or simple name).
+
+        Java field/initializer-block call sites are retained as synthetic
+        ``<init>``/``<clinit>`` graph nodes.  By default they are reported
+        separately in ``initializer_callers`` instead of being counted as
+        source-declared method/constructor callers.  Set
+        ``include_initializers=True`` for the conservative executable-context
+        view used by earlier impact reports.
+        """
+        matches = self.find_nodes(query)
+        if not matches:
+            return {"query": query, "matches": [], "error": "no matching node"}
+        # Bugfix: matches[0] alone used to silently drop the impact of any
+        # other genuinely distinct entity sharing the query's simple name
+        # (see _distinct_impact_targets). Merge across every distinct
+        # target so a caller of the unpicked entity is never lost; report
+        # display fields (target/target_name/...) still reflect the first
+        # one for a stable, single-line summary.
+        targets = self._distinct_impact_targets(matches)
+        target_id = targets[0]
+        target = self._nodes[target_id]
+        # P1.6: changing a container (class/module) implicitly changes all
+        # its members — direct callers of any member are direct impact.
+        members: List[str] = []
+        seed_set: Set[str] = set()
+        all_direct_set: Set[str] = set()
+        for t in targets:
+            t_members = self.get_container_members(t)
+            members.extend(m for m in t_members if m not in seed_set)
+            seed_set.update(t_members)
+            seed_set.add(t)
+            all_direct_set.update(self._direct_callers(t))
+            for m in t_members:
+                all_direct_set.update(self._direct_callers(m))
+        all_direct_set -= seed_set
+        initializer_set = {
+            node_id for node_id in all_direct_set
+            if self._is_initializer_node(node_id)
+        }
+        direct_set = (
+            all_direct_set if include_initializers
+            else all_direct_set - initializer_set
+        )
+        direct = sorted(direct_set - seed_set)
+        initializer_callers = sorted(initializer_set)
+        # PM.3: expose per-caller confidence as a list of objects (each carrying
+        # a "confidence" key) so the monitor's _collect_refs harvests it — a
+        # {id: conf} map would not be, since that harvester only reads floats
+        # stored under a key literally named "confidence". Additive only; the
+        # direct_callers / transitive_callers shapes above are untouched.
+        conf_by_id: Dict[str, Tuple[float, str]] = {}
+        direct_family_seeds: Set[str] = set()
+        for base in (*targets, *members):
+            direct_family_seeds.update(self._override_family(base))
+        for seed in direct_family_seeds:
+            for src, etype, conf in self._impact_in_edges(
+                seed, edge_types=self.DIRECT_CALLER_EDGE_TYPES
+            ):
+                if src not in all_direct_set or src in seed_set:
+                    continue
+                prev = conf_by_id.get(src)
+                if prev is None or conf > prev[0]:
+                    conf_by_id[src] = (conf, etype)
+        caller_confidence = [
+            {"id": cid, "confidence": conf, "edge_type": etype}
+            for cid, (conf, etype) in sorted(conf_by_id.items())
+            if cid in direct_set
+        ]
+        initializer_caller_confidence = [
+            {"id": cid, "confidence": conf, "edge_type": etype}
+            for cid, (conf, etype) in sorted(conf_by_id.items())
+            if cid in initializer_set
+        ]
+        # direct_callers/direct_caller_count union every IMPACT_EDGE_TYPES kind
+        # (TYPE_OF, RETURNS, INSTANTIATES, ...) — for a class target that means
+        # "who depends on this type", not "who constructs it". instantiators
+        # narrows that down to actual `Target(...)` call sites so a class's
+        # constructor-caller count can be read independently of its broader
+        # type-dependent blast radius. Computed as its own INSTANTIATES-only
+        # pass rather than filtered out of caller_confidence: conf_by_id keeps
+        # only the highest-confidence edge per caller, and a heuristic
+        # INSTANTIATES resolution (e.g. 0.85, dict/alias dispatch) can lose
+        # that slot to a same-caller TYPE_OF/RETURNS edge at 1.0 — a caller
+        # that genuinely constructs the target would then vanish from
+        # instantiators even though the INSTANTIATES edge exists.
+        instantiator_conf_by_id: Dict[str, float] = {}
+        for seed in direct_family_seeds:
+            for src, etype, conf in self._impact_in_edges(
+                seed, edge_types=frozenset({EdgeType.INSTANTIATES.name})
+            ):
+                if src not in direct_set or src in seed_set:
+                    continue
+                if conf > instantiator_conf_by_id.get(src, -1.0):
+                    instantiator_conf_by_id[src] = conf
+        instantiator_confidence = [
+            {"id": cid, "confidence": conf, "edge_type": EdgeType.INSTANTIATES.name}
+            for cid, conf in sorted(instantiator_conf_by_id.items())
+        ]
+        instantiators = [entry["id"] for entry in instantiator_confidence]
+        all_transitive: Dict[str, int] = {}
+        for t in targets:
+            for nid, depth in self.get_transitive_callers(t).items():
+                if nid not in all_transitive or depth < all_transitive[nid]:
+                    all_transitive[nid] = depth
+        transitive_initializer_callers = {
+            nid: depth for nid, depth in all_transitive.items()
+            if self._is_initializer_node(nid)
+        }
+        transitive = (
+            all_transitive if include_initializers
+            else {
+                nid: depth for nid, depth in all_transitive.items()
+                if not self._is_initializer_node(nid)
+            }
+        )
+        entry_points = [c for c in transitive if self._nodes.get(c) and self._nodes[c].is_entry_point]
+        affected_files = sorted({
+            # Initializer nodes are hidden caller *units* by default, not lost
+            # dependencies: their source files remain affected and actionable.
+            self._nodes[c].file_path for c in all_transitive if c in self._nodes
+        } | {self._nodes[t].file_path for t in targets if t in self._nodes})
+        # Transitive counterpart of `instantiators` — see
+        # get_transitive_instantiators for why this can't just be filtered
+        # out of `transitive`/`all_transitive` (those are seeded with the
+        # full IMPACT_EDGE_TYPES union at every hop, not just INSTANTIATES).
+        all_transitive_instantiators: Dict[str, int] = {}
+        for t in targets:
+            for nid, depth in self.get_transitive_instantiators(t).items():
+                if nid not in all_transitive_instantiators or depth < all_transitive_instantiators[nid]:
+                    all_transitive_instantiators[nid] = depth
+        transitive_instantiators = (
+            all_transitive_instantiators if include_initializers
+            else {
+                nid: depth for nid, depth in all_transitive_instantiators.items()
+                if not self._is_initializer_node(nid)
+            }
+        )
+        # P4.10 follow-up: node/search/graph payloads already carry `language`
+        # via _node_summary(); impact/plan/verify never did. `node_languages`
+        # covers every id surfaced anywhere above so a polyglot repo's callers
+        # can be attributed to a backend. Filtered to `self._nodes` since ids
+        # sourced from `self.graph` (transitive/members) aren't guaranteed to
+        # have a live node.
+        node_ids = (
+            set(targets) | set(members) | set(direct) | set(initializer_callers)
+            | set(transitive) | set(transitive_initializer_callers)
+            | set(entry_points) | set(transitive_instantiators)
+        )
+        if len(matches) > 1:
+            node_ids |= set(matches)
+        node_languages = {
+            nid: self._nodes[nid].language for nid in node_ids if nid in self._nodes
+        }
+        return {
+            "query": query,
+            "target": target_id,
+            "target_name": target.name,
+            "target_file": target.file_path,
+            "target_language": target.language,
+            "ambiguous_matches": matches if len(matches) > 1 else [],
+            "ambiguous_targets": targets if len(targets) > 1 else [],
+            "affected_members": members,
+            "affected_member_count": len(members),
+            "include_initializers": include_initializers,
+            "initializer_callers": initializer_callers,
+            "initializer_caller_count": len(initializer_callers),
+            "initializer_caller_confidence": initializer_caller_confidence,
+            "transitive_initializer_callers": transitive_initializer_callers,
+            "transitive_initializer_caller_count": len(transitive_initializer_callers),
+            "direct_callers": direct,
+            "direct_caller_count": len(direct),
+            "caller_confidence": caller_confidence,
+            "instantiators": instantiators,
+            "instantiator_count": len(instantiators),
+            "instantiator_confidence": instantiator_confidence,
+            "transitive_callers": transitive,
+            "transitive_caller_count": len(transitive),
+            "transitive_instantiators": transitive_instantiators,
+            "transitive_instantiator_count": len(transitive_instantiators),
+            "affected_entry_points": entry_points,
+            "affected_entry_count": len(entry_points),
+            "affected_files": affected_files,
+            "affected_file_count": len(affected_files),
+            "node_languages": node_languages,
+            "user_facing": bool(entry_points),
+            "max_depth": max(transitive.values()) if transitive else 0,
+        }
+
+    def god_nodes(self, top_n: int = 10) -> List[Dict[str, Any]]:
+        """Top N nodes by total degree (in+out), excluding builtin-denied names.
+
+        These are architectural linchpins: highest blast radius when changed,
+        first place to look when onboarding to an unfamiliar repo.
+        """
+        scores = [
+            (nid, self.graph.in_degree(nid) + self.graph.out_degree(nid))
+            for nid in self.graph.nodes
+            if nid in self._nodes and not self._is_denied(self._nodes[nid].name)
+        ]
+        scores.sort(key=lambda x: x[1], reverse=True)
+        result = []
+        for nid, degree in scores[:top_n]:
+            node = self._nodes.get(nid)
+            result.append({
+                "id": nid,
+                "degree": degree,
+                "in_degree": self.graph.in_degree(nid),
+                "out_degree": self.graph.out_degree(nid),
+                "type": node.node_type.name if node else "UNKNOWN",
+                "file": node.file_path if node else None,
+                "line": node.line if node else None,
+            })
+        return result
+
+    def surprising_connections(self) -> List[Dict[str, Any]]:
+        """CALLS/INSTANTIATES edges that cross Louvain community boundaries.
+
+        Within-community edges are expected coupling. Cross-community edges
+        may signal accidental coupling worth investigating.
+        """
+        from adl_drift.graph.cluster import detect_communities
+        membership = detect_communities(self.graph)
+        result = []
+        seen: Set[Tuple] = set()
+        for src, tgt, data in self.graph.edges(data=True):
+            etype = data.get("type", "")
+            if etype not in ("CALLS", "INSTANTIATES"):
+                continue
+            src_com = membership.get(src)
+            tgt_com = membership.get(tgt)
+            if src_com is None or tgt_com is None or src_com == tgt_com:
+                continue
+            key = (src, tgt, etype)
+            if key in seen:
+                continue
+            seen.add(key)
+            result.append({
+                "from": src,
+                "to": tgt,
+                "edge_type": etype,
+                "confidence": data.get("confidence", 1.0),
+                "from_community": src_com,
+                "to_community": tgt_com,
+            })
+        result.sort(key=lambda x: -x["confidence"])
+        return result
+
+    def stats(self) -> Dict[str, Any]:
+        """Graph statistics: node/edge counts grouped by type."""
+        edge_types: Dict[str, int] = defaultdict(int)
+        for _, _, d in self.graph.edges(data=True):
+            edge_types[d.get("type", "UNKNOWN")] += 1
+        node_types: Dict[str, int] = defaultdict(int)
+        for n in self._nodes.values():
+            node_types[n.node_type.name] += 1
+        return {
+            "total_nodes": len(self._nodes),
+            "total_edges": self.graph.number_of_edges(),
+            "total_edge_occurrences": len(self._edge_occurrences),
+            "node_types": dict(node_types),
+            "edge_types": dict(edge_types),
+            "entry_points": len(self.get_entry_points()),
+            "node_collisions": len(self.node_collisions),
+        }
+
+    def integrity_report(self) -> Dict[str, Any]:
+        """Return deterministic P3.3 graph-integrity violations.
+
+        A graph may be traversable even if its persisted edge list is stale,
+        so validate both representations.  The report is deliberately data,
+        rather than an exception, so CI and MCP callers can surface every
+        violation in one run.
+        """
+        node_ids = list(self._nodes)
+        duplicate_ids = sorted(
+            node_id for node_id, n in Counter(node_ids).items() if n > 1
+        )
+        dangling_edges = sorted(
+            (edge.source, edge.target, edge.edge_type.name)
+            for edge in self._edges
+            if edge.source not in self._nodes or edge.target not in self._nodes
+        )
+        missing_graph_edges = sorted(
+            (edge.source, edge.target, edge.edge_type.name)
+            for edge in self._edges
+            if edge.source in self._nodes and edge.target in self._nodes
+            and not self.graph.has_edge(edge.source, edge.target, key=edge.edge_type.name)
+        )
+        collisions = sorted(
+            {node.id for node in self.node_collisions.values()}
+        )
+        return {
+            "duplicate_node_ids": duplicate_ids,
+            "dangling_edges": dangling_edges,
+            "missing_graph_edges": missing_graph_edges,
+            "symbol_collisions": collisions,
+            "ok": not (duplicate_ids or dangling_edges or missing_graph_edges or collisions),
+        }
+
+    # ---- internal helpers ----
+
+    def _import_map_for(self, result: AnalysisResult, module_name: str) -> Dict[str, str]:
+        """Build {local_binding: dotted_path} for a file.
+
+        Prefers structured ImportRecords (P2.1: handles relative imports,
+        multi-line parenthesized lists, aliases, conditional imports).
+        Falls back to the regex parser for cached AnalysisResults that
+        predate import_records.
+        """
+        records = getattr(result, "import_records", None)
+        if records:
+            return self._import_map_from_records(records, module_name)
+        return self._build_import_map(result.imports)
+
+    @staticmethod
+    def _record_module(r, pkg_parts: List[str]) -> str:
+        """Resolve one ImportRecord's ``module`` field against relative-import
+        level (P2.1) — shared by `_import_map_from_records` (bound imports)
+        and `_wildcard_packages_for` (wildcard imports, which have no
+        binding but still name a package)."""
+        if r.level > 0:
+            keep = len(pkg_parts) - (r.level - 1)
+            base = pkg_parts[:keep] if keep > 0 else []
+            mod_parts = base + ([p for p in r.module.split(".") if p] if r.module else [])
+            return ".".join(mod_parts)
+        return r.module
+
+    @staticmethod
+    def _import_map_from_records(records, module_name: str) -> Dict[str, str]:
+        """{binding: dotted_path} from ImportRecords.
+
+        Relative imports resolve against the importing file's package:
+        for module ``pkg.sub.mod``, level 1 → ``pkg.sub``, level 2 → ``pkg``.
+        """
+        out: Dict[str, str] = {}
+        pkg_parts = module_name.split(".")[:-1]
+        for r in records:
+            binding = r.binding
+            if binding is None:  # wildcard — nothing to bind; see _wildcard_packages_for
+                continue
+            module = CallGraphBuilder._record_module(r, pkg_parts)
+            if r.name and not r.is_wildcard:
+                out[binding] = f"{module}.{r.name}" if module else r.name
+            else:
+                out[binding] = module
+        return out
+
+    def _wildcard_packages_for(self, result: AnalysisResult, module_name: str) -> List[str]:
+        """Package names named by a wildcard import (``import lib.*;``) for a
+        file — the piece `_import_map_from_records` drops entirely, since a
+        wildcard `ImportRecord.binding` is `None` and carries no entry in the
+        {local_name: dotted_path} map. A language resolver that wants to
+        approximate "search the wildcard-imported package" for an otherwise
+        unresolved type (Java's `_resolve_declared_type`) reads this list
+        instead."""
+        records = getattr(result, "import_records", None)
+        if not records:
+            return []
+        pkg_parts = module_name.split(".")[:-1]
+        return [
+            module
+            for r in records
+            if r.is_wildcard and not r.is_static and (module := self._record_module(r, pkg_parts))
+        ]
+
+    def _static_wildcard_classes_for(
+        self, result: AnalysisResult, module_name: str
+    ) -> List[str]:
+        """Fully-qualified class paths named by a *static* wildcard import
+        (``import static a.b.C.*;``) for a file — the static analogue of
+        `_wildcard_packages_for`. A static wildcard imports every static
+        *member* of class `a.b.C`, so (unlike a plain wildcard, which names a
+        *package* to search for types) this names a *class* whose members a
+        bare, receiver-less call may resolve to. The `ImportRecord.module`
+        for `import static a.b.C.*;` is the whole `a.b.C` path (the class),
+        so it is returned as-is (relative-level-resolved via
+        `_record_module`, matching `_wildcard_packages_for`)."""
+        records = getattr(result, "import_records", None)
+        if not records:
+            return []
+        pkg_parts = module_name.split(".")[:-1]
+        return [
+            cls
+            for r in records
+            if r.is_wildcard and r.is_static and (cls := self._record_module(r, pkg_parts))
+        ]
+
+    @staticmethod
+    def _build_import_map(imports: List[str]) -> Dict[str, str]:
+        """Parse import strings → {local_name: dotted_module_path}.
+
+        Handles:
+            import a.b           → {a: a.b}        (use leftmost as binding)
+            import a.b as c      → {c: a.b}
+            from x.y import z    → {z: x.y.z}
+            from x.y import z as q → {q: x.y.z}
+            from x import a, b   → {a: x.a, b: x.b}
+        """
+        out: Dict[str, str] = {}
+        for stmt in imports:
+            stmt = stmt.strip().rstrip(";")
+            if stmt.startswith("from "):
+                m = re.match(r"from\s+([.\w]+)\s+import\s+(.+)", stmt)
+                if not m:
+                    continue
+                module, names = m.group(1), m.group(2)
+                for part in names.split(","):
+                    part = part.strip().rstrip(")").lstrip("(").strip()
+                    if not part or part == "*":
+                        continue
+                    if " as " in part:
+                        orig, alias = [x.strip() for x in part.split(" as ", 1)]
+                        out[alias] = f"{module}.{orig}"
+                    else:
+                        out[part] = f"{module}.{part}"
+            elif stmt.startswith("import "):
+                rest = stmt[len("import "):].strip()
+                for part in rest.split(","):
+                    part = part.strip()
+                    if " as " in part:
+                        mod, alias = [x.strip() for x in part.split(" as ", 1)]
+                        out[alias] = mod
+                    else:
+                        # bind leftmost segment
+                        out[part.split(".")[0]] = part
+        return out
+
+    def harvest_literal_candidates(
+        self,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+    ) -> int:
+        """Optional low-confidence candidate-edge pass over literal/dynamic
+        dispatch idioms — delegated to the active language's `CallResolver`
+        (P4.4). Python's P2.13/P2.22/P2.23 dict-router/callable-alias
+        harvesting lives in `lang/python/resolver.py::
+        PythonCallResolver.harvest_literal_candidates`; languages without an
+        equivalent pattern (Java, for now) get `CallResolver`'s no-op
+        default. Returns the number of edges added.
+        """
+        return self._get_resolver().harvest_literal_candidates(parses, results)
+
+    def _iter_func_cst(self, root, source: bytes, module_name: str):
+        """Python-CST function-definition iterator — kept as a
+        `CallGraphBuilder` method (rather than only living on
+        `PythonCallResolver`) because three call sites outside the resolver
+        reach into it directly: `cli/commands.py` (literal-eval synthetic-
+        function attribution), `server/handlers.py` (single-file rescan), and
+        `detectors/taint.py` (P4.6's function index). None of those are part
+        of this task's scope (P4.6/P4.8/P4.10), so this stays a thin
+        delegation to the active resolver rather than being redesigned.
+        Python-only for now — Java's grammar has no `function_definition`
+        node, matching the fact that none of those three call sites are
+        wired for a Java builder yet either.
+        """
+        return self._get_resolver()._iter_func_cst(root, source, module_name)
+
+    def _is_denied(self, name: str) -> bool:
+        """P2.7/P4.4: built-ins and dunders are never fuzzy-resolved.
+
+        Language-agnostic since P4.4: the deny-list itself
+        (`PYTHON_BUILTINS` / Java's `java.lang.Object` + collection methods)
+        comes from the active resolver's `ResolverConfig.builtins_deny_list`
+        rather than a hardcoded Python module global. The dunder check is a
+        harmless no-op for Java (no `__x__` naming convention there).
+        """
+        deny = self._get_resolver().config.builtins_deny_list
+        return name in deny or (name.startswith("__") and name.endswith("__"))
+
+    def _resolve_chain_root(
+        self,
+        name: str,
+        module_name: str,
+        import_map: Dict[str, str],
+        by_module_symbol: Dict[str, Dict[str, str]],
+        param_types: Optional[Dict[str, str]] = None,
+    ) -> Optional[str]:
+        """Resolve the first link of a receiver chain to a node id.
+
+        Strategies: annotated parameter (P2.2) → same-module symbol →
+        import map (symbol, then module node, then suffix match against
+        module nodes). No fuzzy fallback.
+        """
+        if param_types and name in param_types:
+            cls_id = self._resolve_annotation(
+                param_types[name], module_name, import_map, {}, by_module_symbol,
+            )
+            if cls_id:
+                return cls_id
+        tid = by_module_symbol.get(module_name, {}).get(name)
+        if tid:
+            return tid
+        if name in import_map:
+            resolved = import_map[name]
+            namespace = self._module_namespace(module_name)
+            tid = self._lookup_qualified(resolved, by_module_symbol, namespace)
+            if tid:
+                return tid
+            tid = self._node_for_dotted(resolved, namespace)
+            if tid:
+                return tid
+            module_id = self._module_suffixes().get((namespace, resolved))
+            if module_id:
+                return module_id
+        return None
+
+    def _contains_child(self, node_id: str, name: str) -> Optional[str]:
+        """Find the CONTAINS child of `node_id` whose simple name is `name`."""
+        if node_id not in self.graph:
+            return None
+        for _, child, d in self.graph.out_edges(node_id, data=True):
+            if d.get("type") != EdgeType.CONTAINS.name:
+                continue
+            n = self._nodes.get(child)
+            if n is not None and n.name == name:
+                return child
+        return None
+
+    def _inherits_parents(self, class_id: str) -> List[str]:
+        """Direct INHERITS targets (base classes) of a class node."""
+        if class_id not in self.graph:
+            return []
+        return [
+            t for _, t, d in self.graph.out_edges(class_id, data=True)
+            if d.get("type") == EdgeType.INHERITS.name
+        ]
+
+    def _find_method_on_ancestors(self, class_id: str, method: str) -> Optional[str]:
+        """P2.2: BFS up the INHERITS chain looking for `method`.
+
+        Starts at the *parents* of `class_id` (the class itself was already
+        checked by the caller). Requires INHERITS edges, which
+        `resolve_relationships()` emits before `resolve_calls()` runs.
+        """
+        q: deque[str] = deque(self._inherits_parents(class_id))
+        seen: Set[str] = {class_id}
+        while q:
+            cur = q.popleft()
+            if cur in seen:
+                continue
+            seen.add(cur)
+            child = self._contains_child(cur, method)
+            if child:
+                return child
+            q.extend(self._inherits_parents(cur))
+        return None
+
+    _GENERIC_WRAPPERS = re.compile(
+        r"^(?:typing\.)?(?:Optional|List|Set|FrozenSet|Tuple|Sequence|"
+        r"Iterable|Iterator|Dict|Mapping|MutableMapping|Type|Annotated|"
+        r"ClassVar|Final|Awaitable|Callable)\s*\[(.+)\]$"
+    )
+    # P4.4: Java generic wrapper — ``java.util.List<User>`` / ``Map<K, V>``.
+    # `[\w.$]+` covers scoped/qualified type names (``java.util.List``).
+    _JAVA_GENERIC_WRAPPER = re.compile(r"^[\w.$]+<(.+)>$")
+    _JAVA_WILDCARD_BOUND = re.compile(r"^\?\s+(?:extends|super)\s+(.+)$")
+
+    @staticmethod
+    def _split_top_level(text: str) -> List[str]:
+        """Split ``text`` on top-level commas only, respecting ``<...>``
+        nesting depth — e.g. ``String, Map<K, V>`` → ``["String", "Map<K, V>"]``
+        rather than splitting inside the nested generic."""
+        parts: List[str] = []
+        depth = 0
+        cur: List[str] = []
+        for ch in text:
+            if ch == "<":
+                depth += 1
+            elif ch == ">":
+                depth -= 1
+            if ch == "," and depth == 0:
+                parts.append("".join(cur))
+                cur = []
+            else:
+                cur.append(ch)
+        parts.append("".join(cur))
+        return parts
+
+    def _resolve_annotation(
+        self,
+        ann: str,
+        module_name: str,
+        import_map: Dict[str, str],
+        by_simple_name: Dict[str, List[str]],
+        by_module_symbol: Dict[str, Dict[str, str]],
+    ) -> Optional[str]:
+        """P2.2/P4.4: resolve annotation text to a CLASS node id.
+
+        Strips quotes (forward refs), generic wrappers — Python's
+        ``Optional[User]``, ``List[User]``, ``Dict[str, User]`` → ``User``,
+        and Java's ``List<User>``, ``Map<String, User>`` → ``User`` (last
+        type argument, depth-aware comma split so ``Map<K, List<V>>`` doesn't
+        split inside the nested generic; a ``? extends T`` / ``? super T``
+        wildcard bound resolves to ``T``) — and ``X | None`` unions, then
+        resolves via same-module / import map (strict — no fuzzy fallback).
+        Returns None for builtins, external types, and bare ``?`` wildcards.
+
+        This mirrors ``List[X]`` → ``X`` for TYPE_OF/RETURNS-style "what does
+        this annotation carry" edges. It is deliberately *not* what
+        `lang/java/resolver.py` uses to resolve a typed *receiver* for method
+        dispatch (`Box<T> b; b.get()` must look up `get` on raw `Box`, not
+        `T`) — that path uses `lang.java.ids.erased_type()` instead, which
+        strips generics to the raw type rather than descending into them.
+        """
+        ann = ann.strip().strip("'\"")
+        # Peel generic wrappers (possibly nested: Optional[List[User]])
+        while True:
+            m = self._GENERIC_WRAPPERS.match(ann)
+            if m:
+                # Dict[str, User] → last type argument carries the value type
+                ann = m.group(1).split(",")[-1].strip().strip("'\"")
+                continue
+            jm = self._JAVA_GENERIC_WRAPPER.match(ann)
+            if jm:
+                last = self._split_top_level(jm.group(1))[-1].strip()
+                wm = self._JAVA_WILDCARD_BOUND.match(last)
+                ann = wm.group(1).strip() if wm else last
+                continue
+            break
+        if "|" in ann:  # PEP 604 unions: User | None
+            parts = [p.strip() for p in ann.split("|") if p.strip() not in ("None", "")]
+            ann = parts[0] if parts else ""
+        if not ann or not all(c.isalnum() or c in "._" for c in ann):
+            return None
+        tid = self._resolve_name(
+            ann, module_name, import_map, by_simple_name, by_module_symbol,
+            strict=True,
+        )
+        if tid and self._nodes[tid].node_type == NodeType.CLASS:
+            return tid
+        return None
+
+    def _node_for_dotted(self, dotted: str, namespace: str = "") -> Optional[str]:
+        """P1.10 step 4: resolve a dotted path whose module/qualname boundary
+        is unknown (import-map values) to a node id.
+
+        ``a.b.c`` may be module ``a.b.c``, function ``c`` in module ``a.b``
+        (id ``a.b:c``), or method ``c`` on class ``b`` in ``a/__init__.py``
+        (id ``a:b.c``). Module ids carry no colon, so try the whole path
+        first, then every ``:`` split — longest module prefix wins (matches
+        Python's import semantics: ``from a.b import c`` prefers module
+        ``a.b``).
+        """
+        prefix = f"{namespace}::" if namespace else ""
+        if f"{prefix}{dotted}" in self._nodes:
+            return f"{prefix}{dotted}"
+        parts = dotted.split(".")
+        for i in range(len(parts) - 1, 0, -1):
+            cand = f"{prefix}{'.'.join(parts[:i])}:{'.'.join(parts[i:])}"
+            if cand in self._nodes:
+                return cand
+        if namespace:
+            suffixes = [dotted] + [
+                f"{'.'.join(parts[:i])}:{'.'.join(parts[i:])}"
+                for i in range(len(parts) - 1, 0, -1)
+            ]
+            if self._global_dotted_index is None:
+                index: Dict[str, List[str]] = defaultdict(list)
+                for nid in self._nodes:
+                    if "::" not in nid:
+                        continue
+                    suffix = nid.split("::", 1)[1]
+                    index[suffix].append(nid)
+                self._global_dotted_index = index
+            candidates = {
+                candidate
+                for suffix in suffixes
+                for candidate in self._global_dotted_index.get(suffix, [])
+                if self._namespace_visible(
+                    namespace, self._module_namespace(candidate)
+                )
+            }
+            if len(candidates) == 1:
+                return next(iter(candidates))
+        return None
+
+    def _unique_class_by_simple_name(
+        self, name: str, namespace: str = ""
+    ) -> Optional[str]:
+        """The sole CLASS node named `name`, or None if zero or multiple.
+
+        Backs the Java resolver's global unique-simple-name fallback (P4.4
+        §5.2/§5.9): a project-wide index built once and lazily invalidated
+        exactly like `_global_dotted_index`, instead of scanning every node
+        on every call — P0 profiling found the previous per-call scan was
+        ~52% of total JUnit5 resolve_calls time (`types.py:719`).
+        """
+        if self._class_by_simple_name_index is None:
+            index: Dict[str, Optional[str]] = {}
+            # Same pass also records every CLASS node per simple name with
+            # its module namespace, so the namespace-scoped variant below
+            # filters a handful of same-named classes instead of re-scanning
+            # all nodes per call — that scan is exactly the P0 root cause
+            # this index exists to remove, and it had crept back in with the
+            # `namespace` parameter (JUnit5 resolve_calls 59s -> 651s).
+            by_name: Dict[str, List[Tuple[str, str]]] = {}
+            for nid, node in self._nodes.items():
+                if node.node_type != NodeType.CLASS:
+                    continue
+                if node.name not in index:
+                    index[node.name] = nid
+                elif index[node.name] != nid:
+                    index[node.name] = None
+                by_name.setdefault(node.name, []).append(
+                    (nid, self._module_namespace(node.module))
+                )
+            self._class_by_simple_name_index = index
+            self._classes_by_simple_name = by_name
+        if not namespace:
+            return self._class_by_simple_name_index.get(name)
+        candidates = [
+            nid for nid, node_namespace in self._classes_by_simple_name.get(name, ())
+            if self._namespace_visible(namespace, node_namespace)
+        ]
+        return candidates[0] if len(candidates) == 1 else None
+
+    def _lookup_qualified(
+        self,
+        qualified: str,
+        by_module_symbol: Dict[str, Dict[str, str]],
+        namespace: str = "",
+    ) -> Optional[str]:
+        """Given a dotted name like 'pkg.mod.symbol', find node id by trying
+        progressively shorter module prefixes."""
+        cache_key = (namespace, qualified)
+        if cache_key in self._qualified_lookup_cache:
+            return self._qualified_lookup_cache[cache_key]
+        parts = qualified.split(".")
+        if len(parts) < 2:
+            return None
+        sym = parts[-1]
+        # Try suffix matches against stored module names
+        for mod, syms in by_module_symbol.items():
+            if self._module_namespace(mod) != namespace:
+                continue
+            if sym not in syms:
+                continue
+            mod_parts = self._display_module(mod).split(".")
+            # check if mod ends with parts[:-1] (suffix match — accommodates _path_to_module trimming)
+            target_mod_parts = parts[:-1]
+            if mod_parts[-len(target_mod_parts):] == target_mod_parts \
+               or target_mod_parts[-len(mod_parts):] == mod_parts:
+                self._qualified_lookup_cache[cache_key] = syms[sym]
+                return syms[sym]
+        if namespace:
+            candidates = set()
+            for mod, syms in by_module_symbol.items():
+                if not self._namespace_visible(namespace, self._module_namespace(mod)):
+                    continue
+                if sym not in syms:
+                    continue
+                mod_parts = self._display_module(mod).split(".")
+                target_mod_parts = parts[:-1]
+                if mod_parts[-len(target_mod_parts):] == target_mod_parts \
+                   or target_mod_parts[-len(mod_parts):] == mod_parts:
+                    candidates.add(syms[sym])
+            if len(candidates) == 1:
+                result = next(iter(candidates))
+                self._qualified_lookup_cache[cache_key] = result
+                return result
+        self._qualified_lookup_cache[cache_key] = None
+        return None
+
+    def to_json(self) -> Dict:
+        """Serialize graph to JSON-serializable dict."""
+        return {
+            "nodes": [n.to_dict() for n in self._nodes.values()],
+            "edges": [e.to_dict() for e in self._edges],
+            "edge_occurrences": [e.to_dict() for e in self._edge_occurrences],
+            "statistics": {
+                "total_nodes": len(self._nodes),
+                "total_edges": len(self._edges),
+                "total_edge_occurrences": len(self._edge_occurrences),
+                "entry_points": len(self.get_entry_points()),
+            }
+        }
+
+    def _path_to_module(self, path: Path) -> str:
+        """Convert file path to Python module name.
+
+        If project_root is set, computes the module name relative to that root.
+        Otherwise falls back to the last 3 path components.
+        """
+        if self.project_root is not None:
+            try:
+                rel = path.relative_to(self.project_root)
+            except ValueError:
+                rel = path
+            parts = rel.with_suffix("").parts
+            if parts and parts[-1] == "__init__":
+                parts = parts[:-1]
+            return ".".join(parts)
+        parts = path.with_suffix("").parts
+        return ".".join(parts[-3:])  # Last 3 components as module
+
+    def _module_for_result(self, result: AnalysisResult) -> str:
+        """Use declared module identity when a language backend provides it."""
+        module = getattr(result, "module_name", None) or self._path_to_module(
+            result.file_path
+        )
+        if result.language == "java":
+            build_module = self._java_build_module_for(result.file_path)
+            if build_module:
+                return f"{build_module}::{module}"
+        if result.language != "python" and len(self._languages_in_project()) > 1:
+            return f"{result.language}::{module}"
+        return module
+
+    def _java_build_module_for(self, file_path: Path) -> Optional[str]:
+        """Return the deepest owning Java build unit.
+
+        Existing reactor-module labels stay unchanged. Independent nested
+        Maven/Gradle roots use their scan-root-relative path, so equal legal
+        FQNs remain stable, distinct graph nodes instead of colliding.
+        """
+        if self.project_root is None:
+            return None
+        if self._java_build_module_roots is None:
+            # Roots are (re)computed together with the per-file cache: a
+            # caller that resets the roots (new project root) must not keep
+            # ownership answers derived from the previous root set.
+            self._java_build_module_cache = {}
+            self._java_build_module_dir_cache = {}
+            try:
+                from adl_drift.lang.java.config import JavaProjectConfig
+                from adl_drift.lang.java.backend import JavaBackend
+                from adl_drift.scanner.discovery import _project_dirs
+
+                project_root = self.project_root.resolve()
+                def has_build_descriptor(path: Path) -> bool:
+                    if any(
+                        (path / marker).is_file()
+                        for marker in JavaBackend.project_markers
+                    ):
+                        return True
+                    return any(
+                        entry.is_file()
+                        and entry.name not in {"settings.gradle", "settings.gradle.kts"}
+                        and entry.name.endswith((".gradle", ".gradle.kts"))
+                        for entry in path.iterdir()
+                    )
+
+                build_dirs = {
+                    path.resolve()
+                    for path in _project_dirs(project_root, JavaBackend.project_markers)
+                    if has_build_descriptor(path)
+                }
+                # A custom Gradle build filename is a real build-unit marker,
+                # but ``JavaProjectConfig`` currently accepts directories and
+                # intentionally discovers only conventional marker names.
+                # Parsing a custom unit through it would walk upward and clone
+                # the outer build's coordinates/dependencies under the child
+                # label.  Keep those roots for identity while limiting config
+                # parsing to roots with a conventional descriptor.
+                configs = {
+                    root: JavaProjectConfig(root)
+                    for root in build_dirs
+                    if any((root / marker).is_file() for marker in JavaBackend.project_markers)
+                }
+                unit_roots = set(build_dirs)
+                reactor_groups: List[Set[Path]] = []
+                for root, config in configs.items():
+                    group = {root}
+                    for module in config.modules:
+                        candidate = (root / module).resolve()
+                        if candidate.is_dir():
+                            group.add(candidate)
+                    unit_roots.update(group)
+                    reactor_groups.append(group)
+
+                # A Gradle settings file may assign arbitrary build filenames
+                # dynamically (for example by walking ``**/*.gradle``).  Static
+                # regex extraction cannot enumerate that reactor, but the build
+                # descriptor directories found above are an exact bounded set.
+                # Treat nested Gradle units as visible members of the settings
+                # reactor; same-unit lookup remains preferred by namespace, and
+                # legal duplicate FQNs no longer overwrite each other.
+                for root in configs:
+                    if not any(
+                        (root / name).is_file()
+                        for name in ("settings.gradle", "settings.gradle.kts")
+                    ):
+                        continue
+                    group: Set[Path] = set()
+                    for candidate in build_dirs:
+                        try:
+                            candidate.relative_to(root)
+                        except ValueError:
+                            continue
+                        if any(
+                            entry.name.endswith((".gradle", ".gradle.kts"))
+                            for entry in candidate.iterdir()
+                            if entry.is_file()
+                        ):
+                            group.add(candidate)
+                    if group:
+                        reactor_groups.append(group)
+
+                if len(unit_roots) <= 1:
+                    self._java_build_module_roots = []
+                    self._java_namespace_visibility = {}
+                else:
+                    labels = {}
+                    for root in unit_roots:
+                        relative = root.relative_to(project_root)
+                        labels[root] = (
+                            "@root" if relative == Path(".") else relative.as_posix()
+                        )
+                    self._java_build_module_roots = sorted(
+                        ((root, label) for root, label in labels.items()),
+                        key=lambda item: len(item[0].parts), reverse=True,
+                    )
+                    visibility = {label: {label} for label in labels.values()}
+                    for group in reactor_groups:
+                        members = {labels[root] for root in group if root in labels}
+                        for member in members:
+                            visibility[member].update(members)
+
+                    coordinates = {}
+                    for root, config in configs.items():
+                        if config.group_id and config.artifact_id:
+                            coordinates[f"{config.group_id}:{config.artifact_id}"] = labels[root]
+                    for root, config in configs.items():
+                        source = labels[root]
+                        for dependency in config.dependencies:
+                            target = coordinates.get(":".join(dependency.split(":")[:2]))
+                            if target:
+                                visibility[source].add(target)
+                    self._java_namespace_visibility = visibility
+            except (OSError, ValueError):
+                self._java_build_module_roots = []
+                self._java_namespace_visibility = {}
+        if not self._java_build_module_roots:
+            return None
+        key = str(file_path)
+        cache = self._java_build_module_cache
+        if key in cache:
+            return cache[key]
+        path = Path(file_path)
+        if os.path.islink(path):
+            resolved = path.resolve()
+        else:
+            # A regular file's real path is its parent's real path plus its
+            # name, so resolve each directory once instead of every file:
+            # Path.resolve() walks the whole chain per call, and on the
+            # fuse-backed working trees this repo is benchmarked on that was
+            # ~1,800 realpath calls (about 4% of a JUnit5 structural build).
+            dir_cache = self._java_build_module_dir_cache
+            parent = str(path.parent)
+            resolved_parent = dir_cache.get(parent)
+            if resolved_parent is None:
+                resolved_parent = dir_cache[parent] = path.parent.resolve()
+            resolved = resolved_parent / path.name
+        owner: Optional[str] = None
+        for root, module in self._java_build_module_roots:
+            try:
+                resolved.relative_to(root)
+                owner = module
+                break
+            except ValueError:
+                continue
+        cache[key] = owner
+        return owner
+
+    def _namespace_visible(self, source: str, candidate: str) -> bool:
+        """Whether source build unit may resolve candidate build unit."""
+        if self._java_namespace_visibility is None:
+            self._java_build_module_for(self.project_root or Path("."))
+        visibility = self._java_namespace_visibility or {}
+        return not source or source not in visibility or candidate in visibility[source]
+
+    def _languages_in_project(self) -> Set[str]:
+        if self._project_languages is None:
+            if self.project_root is None:
+                self._project_languages = set(self.backend_names)
+            else:
+                from adl_drift.scanner.discovery import discover_file_groups
+
+                self._project_languages = set(discover_file_groups(self.project_root))
+        return self._project_languages | self.backend_names
+
+    @staticmethod
+    def _module_namespace(module: str) -> str:
+        return module.split("::", 1)[0] if "::" in module else ""
+
+    @staticmethod
+    def _display_module(module: str) -> str:
+        return module.split("::", 1)[-1]
+
+    def _module_suffixes(self) -> Dict[Tuple[str, str], str]:
+        if self._module_suffix_index is None:
+            index: Dict[Tuple[str, str], str] = {}
+            for nid, node in self._nodes.items():
+                if node.node_type != NodeType.MODULE:
+                    continue
+                parts = self._display_module(nid).split(".")
+                namespace = self._module_namespace(nid)
+                for offset in range(len(parts)):
+                    index.setdefault((namespace, ".".join(parts[offset:])), nid)
+            self._module_suffix_index = index
+        return self._module_suffix_index
+
+    @staticmethod
+    def find_project_root(start: Path) -> Optional[Path]:
+        """Walk up from `start` looking for project root markers.
+
+        Supports Python, Maven, Gradle, and .git fallback markers.
+        Returns the directory containing the marker, or None if not found.
+        """
+        return _find_project_root(start)
+
+    @staticmethod
+    def _symbol_to_id(symbol: Symbol, module: str) -> str:
+        """Generate unique ID for a symbol.
+
+        P1.10 step 4: ``module:qualname`` — a ``:`` separates the module path
+        from the in-module qualname (prior art: setuptools entry points,
+        pytest node ids). Function ``c`` in ``a/b.py`` → ``a.b:c``; method
+        ``c`` on class ``b`` in ``a/__init__.py`` → ``a:b.c`` — never the same
+        string, so the package/class conflation class of collisions is gone.
+
+        P2.17: the qualname uses the full scope_chain (class + function
+        ancestors, with ``<locals>`` after function segments) so two closures
+        with the same simple name in different outer functions get distinct
+        IDs — mirrors CPython's __qualname__. Falls back to ``symbol.parent``
+        for pre-P2.17 Symbol objects with an empty scope_chain.
+        """
+        if symbol.metadata.get("constructor"):
+            name = symbol.signature_key or "()"
+        else:
+            name = f"{symbol.name}{symbol.signature_key or ''}"
+        if symbol.scope_chain:
+            return f"{module}:{'.'.join(symbol.scope_chain)}.{name}"
+        if symbol.parent:
+            return f"{module}:{symbol.parent}.{name}"
+        return f"{module}:{name}"