adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/lang/python/resolver.py

@@ -0,0 +1,1789 @@
+"""Python call-resolution strategy (P4.4, PROBLEMS.md).
+
+Behavior-preserving extraction: everything here moved out of
+`graph/builder.py` verbatim (only `self.` -> `self.builder.` for the
+graph-mechanics/id-resolution helpers that stayed shared, plus the
+hardcoded `("self", "cls")` / `b"super"` receiver checks becoming
+`self.config.receiver_self_names` / `self.config.receiver_super_names` reads
+so the policy really is config-driven, not just relocated). Python's
+resolution results must not change — see `tests/test_graph.py` and friends,
+re-run unchanged after this move.
+
+Owns:
+- `PYTHON_BUILTINS` / `DECORATOR_STUB_TABLE` — the P2.7 deny-list and P2.15
+  decorator-stub table, now packaged into a `ResolverConfig` via
+  `default_python_resolver_config()` instead of living as bare module
+  globals `graph/builder.py` reached into directly.
+- `PythonCallResolver` — the full second-pass CST walk: `resolve_calls()`
+  (self/cls/super, same-module, import-map, chained/typed receivers, P1.13
+  local/instance-attribute type inference, P1.14 return-type chains, P2.14
+  `__getattr__` fallback), `resolve_decorator_types()` (P2.15 stub/own-
+  inference), and `harvest_literal_candidates()` (P2.13/P2.22/P2.23 literal
+  dict-router / callable-alias idioms).
+
+Grammar-agnostic graph-id resolution (`_resolve_name`, `_contains_child`,
+`_find_method_on_ancestors`, `_resolve_annotation`, `_resolve_chain_root`,
+`_lookup_qualified`, `_node_for_dotted`, edge dedupe) stayed on
+`CallGraphBuilder` — reached here via `self.builder` — since none of it is
+Python-CST-coupled; `lang/java/resolver.py` reuses the exact same helpers.
+"""
+
+from __future__ import annotations
+
+import builtins
+from collections import defaultdict
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Set, Tuple
+
+from adl_drift.graph.edges import EdgeType, GraphEdge
+from adl_drift.graph.node import NodeType
+from adl_drift.lang.base import CallResolver, ParseResult, ResolverConfig
+from adl_drift.utils.types import LOCALS_MARKER, AnalysisResult
+
+if TYPE_CHECKING:
+    from adl_drift.graph.builder import CallGraphBuilder
+
+__all__ = [
+    "PYTHON_BUILTINS",
+    "DECORATOR_STUB_TABLE",
+    "PythonCallResolver",
+    "default_python_resolver_config",
+]
+
+# P2.7: names that must never be resolved via the fuzzy / over-approximation
+# strategies. Structural strategies (same-module def, import map, self/cls)
+# still run first, so a genuine local ``def get(...)`` resolves normally —
+# this set only blocks the "link x.get() to every function named get" path.
+_COMMON_METHOD_NAMES = {
+    # dict / set
+    "get", "items", "keys", "values", "update", "pop", "popitem",
+    "setdefault", "clear", "copy", "fromkeys", "add", "discard",
+    "union", "intersection", "difference", "issubset", "issuperset",
+    # list
+    "append", "extend", "insert", "remove", "sort", "reverse",
+    "index", "count",
+    # str / bytes
+    "join", "split", "rsplit", "strip", "lstrip", "rstrip", "replace",
+    "startswith", "endswith", "format", "format_map", "lower", "upper",
+    "title", "capitalize", "casefold", "encode", "decode", "find", "rfind",
+    "ljust", "rjust", "zfill", "splitlines", "partition", "rpartition",
+    # file-like
+    "read", "write", "readline", "readlines", "close", "flush", "seek",
+}
+PYTHON_BUILTINS: Set[str] = set(dir(builtins)) | _COMMON_METHOD_NAMES
+
+# P2.15: framework stub table. Maps decorator simple name → set of attribute
+# names that the framework wrapper adds to the decorated callable.
+# ``send_email.delay()`` where ``send_email`` is ``@task``-decorated resolves
+# to the decorated function itself (conf 0.8, via=decorator_stub).
+DECORATOR_STUB_TABLE: Dict[str, Set[str]] = {
+    # Celery / task queues
+    "task": {
+        "delay", "apply_async", "apply", "signature", "s", "si",
+        "chunks", "map", "starmap", "retry", "run", "AsyncResult", "subtask",
+    },
+    "shared_task": {
+        "delay", "apply_async", "apply", "signature", "s", "si",
+        "chunks", "map", "starmap", "retry", "run", "AsyncResult", "subtask",
+    },
+    # functools caching
+    "lru_cache": {"cache_clear", "cache_info"},
+    "cache": {"cache_clear", "cache_info"},
+    # Click
+    "command": {"callback", "invoke", "make_context", "main", "params", "name"},
+    "group": {
+        "callback", "invoke", "make_context", "main", "params", "name",
+        "add_command", "result_callback",
+    },
+}
+
+
+def default_python_resolver_config() -> ResolverConfig:
+    """The real Python `ResolverConfig` — used both by `PythonBackend.
+    resolver_config()` and as `CallGraphBuilder`'s zero-arg fallback (every
+    pre-P4.4 call site constructs `CallGraphBuilder()` with no config)."""
+    cfg = ResolverConfig(
+        receiver_self_names=("self", "cls"),
+        receiver_super_names=("super",),
+        builtins_deny_list=frozenset(PYTHON_BUILTINS),
+        annotation_stub_table={k: frozenset(v) for k, v in DECORATOR_STUB_TABLE.items()},
+    )
+    cfg.resolver_factory = lambda builder, config: PythonCallResolver(builder, config)
+    return cfg
+
+
+class PythonCallResolver(CallResolver):
+    """Python's `CallResolver` (P4.4) — the exact pre-P4.4
+    `CallGraphBuilder.resolve_calls()`/`_resolve_target()`/
+    `resolve_decorator_types()`/`harvest_literal_candidates()` behavior,
+    relocated."""
+
+    def __init__(self, builder: "CallGraphBuilder", config: ResolverConfig) -> None:
+        super().__init__(builder, config)
+        # P1.13: {class_id: {attr: target_class_id}} from `self.x = Cls(...)`
+        # anywhere in the class's methods. Populated by resolve_calls(),
+        # reused by harvest_literal_candidates()'s P2.22 typed-attribute hop.
+        self._self_attr_types: Dict[str, Dict[str, str]] = {}
+
+    # ------------------------------------------------------------------ main pass
+
+    def resolve_calls(
+        self,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+    ) -> int:
+        """Second pass: emit CALLS edges by walking each function body.
+
+        Resolution order for each call site:
+            1. self.X / cls.X        → method X on enclosing class
+            2. bare identifier X     → function/class X in same module
+            3. module.X via import   → resolved import alias → module → symbol X
+            4. obj.X (unknown obj)   → over-approximate: every node ending in .X
+                                       (confidence flag set on edge)
+        """
+        # Indices
+        by_simple_name: Dict[str, List[str]] = defaultdict(list)
+        by_module_symbol: Dict[str, Dict[str, str]] = defaultdict(dict)
+        var_by_module: Dict[str, Dict[str, str]] = defaultdict(dict)
+        # P2.14: class IDs whose instances have an open attribute universe
+        # (they define __getattr__). Attribute reads on such classes with no
+        # structural match route to Class.__getattr__ instead of vanishing.
+        _getattr_class_ids: Set[str] = set()
+        for nid, node in self.builder._nodes.items():
+            if node.language != "python":
+                continue
+            if node.node_type in (NodeType.FUNCTION, NodeType.CLASS):
+                by_simple_name[node.name].append(nid)
+                by_module_symbol[node.module][node.name] = nid
+                # P2.14: record classes that define __getattr__
+                if (node.node_type == NodeType.FUNCTION
+                        and node.name == "__getattr__"
+                        and node.contained_in):
+                    class_id = f"{node.module}:{node.contained_in}"
+                    if class_id in self.builder._nodes:
+                        _getattr_class_ids.add(class_id)
+            elif node.node_type == NodeType.VARIABLE and not node.contained_in:
+                # module-level variables/constants (class attributes are
+                # reached via the self.X path instead)
+                var_by_module[node.module][node.name] = nid
+
+        # P2.2: param annotation index — caller node id → {param: annotation}.
+        # Lets the resolver infer receiver types for obj.method() calls.
+        param_types_by_id: Dict[str, Dict[str, str]] = {}
+        for ar in results.values():
+            mod = self.builder._module_for_result(ar)
+            for sym in ar.symbols:
+                if sym.kind == "function" and sym.param_types:
+                    param_types_by_id[self.builder._symbol_to_id(sym, mod)] = sym.param_types
+
+        # P1.13: instance-attribute type inference — `self.X = ClassName(...)`
+        # anywhere in a class's methods → {class_id: {attr: target_class_id}}.
+        # Built in a pre-pass so a method using `self.db.query()` resolves even
+        # when `__init__` (where `self.db = Session()` lives) is visited later.
+        self_attr_types: Dict[str, Dict[str, str]] = defaultdict(dict)
+        for file_path, parse in parses.items():
+            result = results.get(file_path)
+            if result is None:
+                continue
+            module_name = self.builder._module_for_result(result)
+            import_map = self.builder._import_map_for(result, module_name)
+            for func_cst, caller_id in self._iter_func_cst(
+                parse.tree.root_node, parse.source_bytes, module_name
+            ):
+                node = self.builder._nodes.get(caller_id)
+                if node is None or not node.contained_in:
+                    continue
+                class_id = f"{module_name}:{node.contained_in}"
+                if class_id not in self.builder._nodes:
+                    continue
+                body = func_cst.child_by_field_name("body")
+                if body is None:
+                    continue
+                for kind, name, cls_id in self._iter_typed_assignments(
+                    body, parse.source_bytes, module_name,
+                    import_map, by_module_symbol,
+                ):
+                    if kind == "self":
+                        self_attr_types[class_id].setdefault(name, cls_id)
+
+        # P2.22: stash for the literal-harvest pass (runs after resolve_calls),
+        # so its callable-dict dispatch can do the same typed-attribute hop.
+        self._self_attr_types = self_attr_types
+
+        edges_added = 0
+        for file_path, parse in parses.items():
+            result = results.get(file_path)
+            if result is None:
+                continue
+            module_name = self.builder._module_for_result(result)
+            import_map = self.builder._import_map_for(result, module_name)
+
+            # Find every function_definition CST node and its caller node_id
+            for func_cst, caller_id in self._iter_func_cst(
+                parse.tree.root_node, parse.source_bytes, module_name
+            ):
+                if caller_id not in self.builder._nodes:
+                    continue
+                caller_node = self.builder._nodes[caller_id]
+                enclosing_class = caller_node.contained_in
+                body = func_cst.child_by_field_name("body")
+                if body is None:
+                    continue
+
+                # P1.13: local-variable type inference for this function body —
+                # `x = ClassName(...)` → {x: class_id}, so `x.method()` resolves.
+                local_var_types: Dict[str, str] = {}
+                for kind, name, cls_id in self._iter_typed_assignments(
+                    body, parse.source_bytes, module_name,
+                    import_map, by_module_symbol,
+                ):
+                    if kind == "local":
+                        local_var_types[name] = cls_id
+
+                for call_node in self._collect_calls(body):
+                    target_id, confidence, dyn_etype = self._resolve_target(
+                        call_node,
+                        parse.source_bytes,
+                        module_name,
+                        enclosing_class,
+                        import_map,
+                        by_simple_name,
+                        by_module_symbol,
+                        param_types_by_id.get(caller_id, {}),
+                        _getattr_class_ids,
+                        local_var_types,
+                        self_attr_types,
+                    )
+                    if not target_id or target_id == caller_id:
+                        continue
+                    is_awaited = (
+                        dyn_etype is None
+                        and call_node.parent is not None
+                        and call_node.parent.type == "await"
+                    )
+                    for tid in target_id if isinstance(target_id, list) else [target_id]:
+                        if tid not in self.builder._nodes:
+                            continue
+                        if dyn_etype is not None:
+                            # P2.14: DYNAMIC_ATTR — use override edge type directly
+                            etype = dyn_etype
+                        else:
+                            # P2.8: Foo() on a class node is construction, not a
+                            # plain call — constructor-signature changes must be
+                            # distinguishable in impact reports.
+                            etype = (
+                                EdgeType.INSTANTIATES
+                                if self.builder._nodes[tid].node_type == NodeType.CLASS
+                                else EdgeType.CALLS
+                            )
+                        edge = GraphEdge(
+                                source=caller_id,
+                                target=tid,
+                                edge_type=etype,
+                                file_path=str(file_path),
+                                line=call_node.start_point[0] + 1,
+                                column=call_node.start_point[1],
+                                start_byte=call_node.start_byte,
+                                end_byte=call_node.end_byte,
+                                confidence=float(confidence),
+                                strategy="python_resolver",
+                            )
+                        self.builder._record_edge_occurrence(edge)
+                        if (caller_id, tid, etype) not in self.builder._edge_keys:
+                            self.builder._add_edge(edge)
+                            caller_node.calls.add(tid)
+                            self.builder._nodes[tid].called_by.add(caller_id)
+                            edges_added += 1
+                        if is_awaited:
+                            await_edge = GraphEdge(
+                                source=caller_id,
+                                target=tid,
+                                edge_type=EdgeType.AWAITS,
+                                file_path=str(file_path),
+                                line=call_node.start_point[0] + 1,
+                                column=call_node.start_point[1],
+                                start_byte=call_node.start_byte,
+                                end_byte=call_node.end_byte,
+                                confidence=float(confidence),
+                                strategy="python_resolver",
+                            )
+                            self.builder._record_edge_occurrence(await_edge)
+                            if not self.builder._has_edge_of_type(
+                                caller_id, tid, EdgeType.AWAITS
+                            ):
+                                self.builder._add_edge(await_edge)
+
+                # P1.8: REFERENCES edges — variable/constant reads in the body
+                name_reads, attr_reads = self._collect_variable_reads(
+                    body, parse.source_bytes
+                )
+                for name, line in name_reads:
+                    if self.builder._is_denied(name):
+                        continue
+                    var_id = var_by_module.get(module_name, {}).get(name)
+                    conf = 0.9
+                    if var_id is None and name in import_map:
+                        var_id = self._lookup_variable(import_map[name], var_by_module)
+                        conf = 0.85
+                    if not var_id or var_id == caller_id:
+                        continue
+                    self.builder._add_edge(GraphEdge(
+                        source=caller_id,
+                        target=var_id,
+                        edge_type=EdgeType.REFERENCES,
+                        file_path=str(file_path),
+                        line=line,
+                        confidence=conf,
+                    ))
+                if enclosing_class:
+                    for attr, line in attr_reads:
+                        var_id = f"{module_name}:{enclosing_class}.{attr}"
+                        var_node = self.builder._nodes.get(var_id)
+                        if var_node is None or var_node.node_type != NodeType.VARIABLE:
+                            continue
+                        self.builder._add_edge(GraphEdge(
+                            source=caller_id,
+                            target=var_id,
+                            edge_type=EdgeType.REFERENCES,
+                            file_path=str(file_path),
+                            line=line,
+                            confidence=0.95,
+                        ))
+        return edges_added
+
+    def _collect_variable_reads(self, body, source: bytes):
+        """P1.8: collect identifier reads and ``self.X`` attribute reads.
+
+        Returns (name_reads, attr_reads), each a list of (name, line).
+        Definition sites are filtered out: assignment LHS targets, for-loop
+        targets, keyword-argument names, and the attribute position of dotted
+        access (only the leftmost identifier is a name lookup).
+        """
+        name_reads: List[Tuple[str, int]] = []
+        attr_reads: List[Tuple[str, int]] = []
+        self_names = self.config.receiver_self_names
+
+        def _is_assignment_lhs(node) -> bool:
+            p = node.parent
+            if p is None:
+                return False
+            if p.type == "assignment" and node == p.child_by_field_name("left"):
+                return True
+            # tuple/list unpack target: x, y = ...
+            if p.type in ("pattern_list", "tuple_pattern", "list_pattern"):
+                gp = p.parent
+                return gp is not None and gp.type == "assignment" \
+                    and p == gp.child_by_field_name("left")
+            return False
+
+        stack = [body]
+        while stack:
+            node = stack.pop()
+            if node.type == "function_definition" and node is not body:
+                continue  # inner function's reads belong to the inner function
+            if node.type == "identifier":
+                p = node.parent
+                text = source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+                if text in self_names:
+                    continue
+                if _is_assignment_lhs(node):
+                    continue
+                if p is not None:
+                    if p.type == "keyword_argument" and node == p.child_by_field_name("name"):
+                        continue
+                    if p.type == "attribute" and node == p.child_by_field_name("attribute"):
+                        continue
+                    if p.type == "for_statement" and node == p.child_by_field_name("left"):
+                        continue
+                name_reads.append((text, node.start_point[0] + 1))
+                continue
+            if node.type == "attribute":
+                obj = node.child_by_field_name("object")
+                attr = node.child_by_field_name("attribute")
+                if obj is not None and attr is not None and obj.type == "identifier":
+                    obj_text = source[obj.start_byte:obj.end_byte].decode("utf-8", errors="replace")
+                    if obj_text in self_names and not _is_assignment_lhs(node):
+                        attr_reads.append((
+                            source[attr.start_byte:attr.end_byte].decode("utf-8", errors="replace"),
+                            node.start_point[0] + 1,
+                        ))
+            stack.extend(node.children)
+        return name_reads, attr_reads
+
+    @staticmethod
+    def _lookup_variable(
+        qualified: str, var_by_module: Dict[str, Dict[str, str]]
+    ) -> Optional[str]:
+        """Resolve 'pkg.mod.CONST' to a VARIABLE node id (suffix-matched,
+        same convention as _lookup_qualified)."""
+        parts = qualified.split(".")
+        if len(parts) < 2:
+            return None
+        sym = parts[-1]
+        target_mod = parts[:-1]
+        for mod, var_names in var_by_module.items():
+            if sym not in var_names:
+                continue
+            mod_parts = mod.split(".")
+            if mod_parts[-len(target_mod):] == target_mod \
+               or target_mod[-len(mod_parts):] == mod_parts:
+                return var_names[sym]
+        return None
+
+    # ------------------------------------------------------------------ P2.15
+
+    def resolve_decorator_types(
+        self,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+    ) -> None:
+        """P2.15: build decorator-rebind and stub maps for _resolve_target.
+
+        For each decorated function, records either a set of stub attribute
+        names (from `self.config.annotation_stub_table`) or a rebound class
+        node id (from narrow own-inference on local decorator bodies).
+        Populated once after resolve_relationships() so that resolve_calls()
+        can consult it.
+        """
+        self.builder._decorator_rebirds.clear()
+
+        by_module_symbol: Dict[str, Dict[str, str]] = defaultdict(dict)
+        by_simple_name: Dict[str, List[str]] = defaultdict(list)
+        for nid, node in self.builder._nodes.items():
+            if node.language != "python":
+                continue
+            if node.node_type in (NodeType.FUNCTION, NodeType.CLASS):
+                by_simple_name[node.name].append(nid)
+                by_module_symbol[node.module][node.name] = nid
+
+        import_maps: Dict[str, Dict[str, str]] = {}
+        for ar in results.values():
+            mod = self.builder._module_for_result(ar)
+            import_maps[str(ar.file_path)] = self.builder._import_map_for(ar, mod)
+
+        for sym_id, (decorators, module_name, file_path, _ln) in \
+                self.builder._pending_decorators.items():
+            if sym_id not in self.builder._nodes:
+                continue
+
+            stub_attrs: Set[str] = set()
+            rebound: Optional[str] = None
+
+            for deco_text in decorators:
+                dname = self.builder._decorator_name(deco_text)
+                if not dname:
+                    continue
+                simple = dname.split(".")[-1]
+
+                # Stub table lookup — simple decorator name only
+                if simple in self.config.annotation_stub_table:
+                    stub_attrs.update(self.config.annotation_stub_table[simple])
+
+                # Own inference: resolve decorator to a function node and
+                # check for a single `return Cls(fn)` body.
+                if rebound is None:
+                    imap = import_maps.get(file_path, {})
+                    deco_fn_id = self.builder._resolve_name(
+                        dname, module_name, imap,
+                        by_simple_name, by_module_symbol,
+                        strict=True,
+                    )
+                    if (
+                        deco_fn_id
+                        and deco_fn_id in self.builder._nodes
+                        and self.builder._nodes[deco_fn_id].node_type == NodeType.FUNCTION
+                    ):
+                        cls_id = self._infer_decorator_return_class(
+                            deco_fn_id, parses, results,
+                            by_module_symbol, import_maps,
+                        )
+                        if cls_id:
+                            rebound = cls_id
+
+            if stub_attrs or rebound:
+                self.builder._decorator_rebirds[sym_id] = (
+                    stub_attrs if stub_attrs else None,
+                    rebound,
+                )
+
+    def _infer_decorator_return_class(
+        self,
+        deco_fn_id: str,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+        by_module_symbol: Dict[str, Dict[str, str]],
+        import_maps: Dict[str, Dict[str, str]],
+    ) -> Optional[str]:
+        """P2.15: return CLASS node id iff decorator body has a single
+        ``return Cls(...)`` where Cls resolves to a known class.
+
+        Narrow own inference — multiple returns or non-class returns yield
+        None so we never mis-bind a complex decorator.
+        """
+        deco_node = self.builder._nodes.get(deco_fn_id)
+        if deco_node is None or not deco_node.file_path:
+            return None
+
+        parse = None
+        fp_key: Optional[Path] = None
+        for fp, pr in parses.items():
+            if str(fp) == deco_node.file_path:
+                parse = pr
+                fp_key = fp
+                break
+        if parse is None:
+            return None
+
+        result = results.get(fp_key)
+        module_name = (
+            self.builder._module_for_result(result)
+            if result is not None
+            else self.builder._path_to_module(fp_key)
+        )
+        imap = import_maps.get(deco_node.file_path, {})
+
+        # Locate the function_definition CST node by line (0-indexed)
+        func_cst = self._find_func_cst_at_line(
+            parse.tree.root_node, deco_node.line - 1
+        )
+        if func_cst is None:
+            return None
+
+        body = func_cst.child_by_field_name("body")
+        if body is None:
+            return None
+
+        # Collect top-level return_statement nodes (skip nested functions)
+        returns = []
+        stack = list(body.children)
+        while stack:
+            node = stack.pop()
+            if node.type == "function_definition":
+                continue
+            if node.type == "return_statement":
+                returns.append(node)
+                continue
+            stack.extend(node.children)
+
+        if len(returns) != 1:
+            return None
+
+        # The return value must be a call: `return Cls(fn)` or `return Cls()`
+        named = returns[0].named_children
+        if not named:
+            return None
+        value = named[0]
+        if value.type != "call":
+            return None
+        fn_part = value.child_by_field_name("function")
+        if fn_part is None or fn_part.type != "identifier":
+            return None
+
+        cls_name = parse.source_bytes[
+            fn_part.start_byte:fn_part.end_byte
+        ].decode("utf-8", errors="replace")
+
+        # Resolve cls_name → CLASS node (same-module first, then imports)
+        cls_id = by_module_symbol.get(module_name, {}).get(cls_name)
+        if cls_id is None and cls_name in imap:
+            resolved = imap[cls_name]
+            parts = resolved.split(".")
+            sym_name = parts[-1]
+            for mod, syms in by_module_symbol.items():
+                if sym_name in syms:
+                    cand = syms[sym_name]
+                    if (
+                        cand in self.builder._nodes
+                        and self.builder._nodes[cand].node_type == NodeType.CLASS
+                    ):
+                        cls_id = cand
+                        break
+
+        if (
+            cls_id
+            and cls_id in self.builder._nodes
+            and self.builder._nodes[cls_id].node_type == NodeType.CLASS
+        ):
+            return cls_id
+        return None
+
+    @staticmethod
+    def _find_func_cst_at_line(root, target_line: int):
+        """Find a function_definition CST node starting at target_line (0-indexed)."""
+        stack = [root]
+        while stack:
+            node = stack.pop()
+            if (
+                node.type == "function_definition"
+                and node.start_point[0] == target_line
+            ):
+                return node
+            stack.extend(node.children)
+        return None
+
+    # ------------------------------------------------------------------ target resolution
+
+    def _resolve_target(
+        self,
+        call_node,
+        source: bytes,
+        module_name: str,
+        enclosing_class: Optional[str],
+        import_map: Dict[str, str],
+        by_simple_name: Dict[str, List[str]],
+        by_module_symbol: Dict[str, Dict[str, str]],
+        param_types: Optional[Dict[str, str]] = None,
+        getattr_class_ids: Optional[Set[str]] = None,
+        local_var_types: Optional[Dict[str, str]] = None,
+        self_attr_types: Optional[Dict[str, Dict[str, str]]] = None,
+    ):
+        """Resolve a `call` node's callable to (target_id_or_list, confidence, edge_type_override).
+
+        `param_types` is the enclosing function's {param: annotation} map —
+        used by the P2.2 conformance strategy to type annotated receivers.
+
+        `local_var_types` (P1.13) is the enclosing function's {var: class_id}
+        map from `x = ClassName(...)` assignments; `self_attr_types` (P1.13) is
+        the global {class_id: {attr: class_id}} map from `self.x = ClassName(...)`.
+        Both let the resolver type otherwise-unannotated receivers, emitting a
+        real edge to the correct method instead of dropping or over-approximating.
+
+        `edge_type_override` is None for normal CALLS/INSTANTIATES/AWAITS
+        resolution; EdgeType.DYNAMIC_ATTR when the target is a __getattr__
+        method reached via the P2.14 open-attribute-universe fallback.
+        """
+        param_types = param_types or {}
+        getattr_class_ids = getattr_class_ids or set()
+        local_var_types = local_var_types or {}
+        self_attr_types = self_attr_types or {}
+        fn_node = call_node.child_by_field_name("function")
+        if fn_node is None:
+            return None, 0.0, None
+
+        # P2.2: super().method() → search INHERITS ancestors of the
+        # enclosing class (receiver is a call node, so the chain flattener
+        # would otherwise skip it).
+        if fn_node.type == "attribute":
+            obj_node = fn_node.child_by_field_name("object")
+            attr_node = fn_node.child_by_field_name("attribute")
+            if (
+                obj_node is not None and obj_node.type == "call"
+                and attr_node is not None and enclosing_class
+            ):
+                inner = obj_node.child_by_field_name("function")
+                if inner is not None and inner.type == "identifier":
+                    inner_text = source[inner.start_byte:inner.end_byte].decode(
+                        "utf-8", errors="replace"
+                    )
+                    if inner_text in self.config.receiver_super_names:
+                        attr = source[attr_node.start_byte:attr_node.end_byte].decode(
+                            "utf-8", errors="replace"
+                        )
+                        tid = self.builder._find_method_on_ancestors(
+                            f"{module_name}:{enclosing_class}", attr
+                        )
+                        if tid:
+                            return tid, 0.85, None
+                        return None, 0.0, None
+
+        if fn_node.type == "identifier":
+            name = source[fn_node.start_byte:fn_node.end_byte].decode("utf-8", errors="replace")
+            # 1. same module
+            if name in by_module_symbol.get(module_name, {}):
+                return by_module_symbol[module_name][name], 0.9, None
+            # 2. imported symbol
+            if name in import_map:
+                resolved = import_map[name]
+                tid = self.builder._lookup_qualified(resolved, by_module_symbol)
+                if tid:
+                    return tid, 0.85, None
+            # 3. any function with this name (ambiguous) — never for
+            #    built-ins (P2.7): a user `def filter(...)` elsewhere must
+            #    not capture every bare `filter(...)` call.
+            if self.builder._is_denied(name):
+                return None, 0.0, None
+            cands = by_simple_name.get(name, [])
+            if len(cands) == 1:
+                return cands[0], 0.6, None
+            return None, 0.0, None
+
+        if fn_node.type == "attribute":
+            chain = self._flatten_attr_chain(fn_node, source)
+            if chain is None:
+                # P1.14: receiver is a call — `f(...).method()`. If `f` has a
+                # declared return type (RETURNS edge) or is a constructor, the
+                # receiver class is known, so resolve the method on it. A known
+                # type decides resolution (found or unresolved) — never
+                # over-approximated (P1.7). Otherwise skip.
+                return self._resolve_return_type_chain(
+                    fn_node, source, module_name, enclosing_class, import_map,
+                    by_simple_name, by_module_symbol, param_types,
+                    getattr_class_ids, local_var_types, self_attr_types,
+                )
+            *receiver, attr = chain
+
+            if len(receiver) == 1:
+                obj = receiver[0]
+                # self.attr / cls.attr → method on enclosing class
+                if obj in self.config.receiver_self_names and enclosing_class:
+                    nid = f"{module_name}:{enclosing_class}.{attr}"
+                    if nid in self.builder._nodes:
+                        return nid, 0.95, None
+                    # P2.2: not defined here → walk the INHERITS chain
+                    tid = self.builder._find_method_on_ancestors(
+                        f"{module_name}:{enclosing_class}", attr
+                    )
+                    if tid:
+                        return tid, 0.85, None
+                    # P2.14: class has open attribute universe (__getattr__)
+                    # and the attr has no structural match — route through
+                    # __getattr__ so impact analysis covers all dynamic reads.
+                    class_id = f"{module_name}:{enclosing_class}"
+                    if class_id in getattr_class_ids:
+                        ga_id = f"{class_id}.__getattr__"
+                        if ga_id in self.builder._nodes:
+                            return ga_id, 0.4, EdgeType.DYNAMIC_ATTR
+                    return None, 0.0, None
+                # P2.2 conformance: annotated parameter receiver —
+                # def f(svc: UserService): svc.notify() → UserService.notify.
+                # When the receiver's declared type is known, resolution is
+                # decided here: either we find the method (on the class or
+                # its INHERITS ancestors) or the call stays unresolved —
+                # never over-approximated.
+                if obj in param_types:
+                    cls_id = self.builder._resolve_annotation(
+                        param_types[obj], module_name, import_map,
+                        by_simple_name, by_module_symbol,
+                    )
+                    if cls_id:
+                        tid = self.builder._contains_child(cls_id, attr) or \
+                            self.builder._find_method_on_ancestors(cls_id, attr)
+                        if tid:
+                            return tid, 0.85, None
+                        # P2.14: declared type has __getattr__ → DYNAMIC_ATTR
+                        if cls_id in getattr_class_ids:
+                            ga_id = f"{cls_id}.__getattr__"
+                            if ga_id in self.builder._nodes:
+                                return ga_id, 0.4, EdgeType.DYNAMIC_ATTR
+                    return None, 0.0, None
+                # P1.13: local-variable type — x = Service(); x.run() →
+                # Service.run. A known inferred type decides resolution here
+                # (method found, inherited, or __getattr__) — never falls back
+                # to global-name over-approximation.
+                if obj in local_var_types:
+                    cls_id = local_var_types[obj]
+                    tid = self.builder._contains_child(cls_id, attr) or \
+                        self.builder._find_method_on_ancestors(cls_id, attr)
+                    if tid:
+                        return tid, 0.8, None
+                    if cls_id in getattr_class_ids:
+                        ga_id = f"{cls_id}.__getattr__"
+                        if ga_id in self.builder._nodes:
+                            return ga_id, 0.4, EdgeType.DYNAMIC_ATTR
+                    return None, 0.0, None
+                # module.attr via import
+                if obj in import_map:
+                    resolved_mod = import_map[obj]
+                    tid = self.builder._lookup_qualified(
+                        f"{resolved_mod}.{attr}", by_module_symbol
+                    )
+                    if tid:
+                        return tid, 0.85, None
+                # ClassName.attr / alias.attr → resolve receiver, walk one
+                # CONTAINS link (P1.7 chained-call strategy, single link)
+                root_id = self.builder._resolve_chain_root(
+                    obj, module_name, import_map, by_module_symbol
+                )
+                if root_id:
+                    child = self.builder._contains_child(root_id, attr)
+                    if child:
+                        return child, 0.75, None
+                    # P2.15: decorated function — check stub table or own-
+                    # inference rebind before falling to over-approximation.
+                    if self.builder._nodes[root_id].node_type == NodeType.FUNCTION:
+                        rebind = self.builder._decorator_rebirds.get(root_id)
+                        if rebind is not None:
+                            stub_attrs, rebound_class_id = rebind
+                            if stub_attrs and attr in stub_attrs:
+                                # Wrapper attr delegates to decorated fn;
+                                # emit CALLS to the function itself so its
+                                # callers appear in blast-radius (conf 0.8).
+                                return root_id, 0.8, None
+                            if rebound_class_id:
+                                method_id = self.builder._contains_child(
+                                    rebound_class_id, attr
+                                )
+                                if method_id:
+                                    return method_id, 0.7, None
+                # fallback: over-approximate by attribute name — never for
+                # built-in / common stdlib method names (P2.7)
+                if self.builder._is_denied(attr):
+                    return None, 0.0, None
+                cands = by_simple_name.get(attr, [])
+                if len(cands) == 1:
+                    return cands[0], 0.5, None
+                if 1 < len(cands) <= 5:
+                    return cands, 0.3, None
+                return None, 0.0, None
+
+            # Multi-link chain (P1.7 + P1.13): e.g. lib.Db.query() →
+            # receiver=["lib", "Db"], attr="query". Resolve chain[0], then walk
+            # one link at a time — jumping through *typed* instance attributes
+            # (self.db = Session()) instead of dead-ending on the attribute
+            # VARIABLE node, which is what made self.x.y() unresolvable.
+            if receiver[0] in self.config.receiver_self_names and enclosing_class:
+                current: Optional[str] = f"{module_name}:{enclosing_class}"
+            elif receiver[0] in local_var_types:
+                current = local_var_types[receiver[0]]
+            else:
+                current = self.builder._resolve_chain_root(
+                    receiver[0], module_name, import_map, by_module_symbol,
+                    param_types,
+                )
+            links = receiver[1:]
+            if current is None or current not in self.builder._nodes:
+                return None, 0.0, None
+            chained_conf = 0.75
+            for link in links:
+                typed = self_attr_types.get(current, {}).get(link)
+                if typed is not None and typed in self.builder._nodes:
+                    current = typed          # P1.13 typed-attribute hop
+                    chained_conf = 0.8
+                    continue
+                nxt = self.builder._contains_child(current, link)
+                if nxt is None:
+                    # Chain broken mid-walk: do NOT fall back to global
+                    # name over-approximation — a missing edge beats 30
+                    # phantom ones (P1.7).
+                    return None, 0.0, None
+                current = nxt
+            # final link is the method/attribute being called — also try the
+            # INHERITS chain (P2.2) so inherited methods on a typed receiver
+            # resolve.
+            tid = self.builder._contains_child(current, attr) or \
+                self.builder._find_method_on_ancestors(current, attr)
+            if tid:
+                return tid, chained_conf, None
+            return None, 0.0, None
+
+        return None, 0.0, None
+
+    def _iter_typed_assignments(
+        self, body, source: bytes, module_name: str,
+        import_map: Dict[str, str],
+        by_module_symbol: Dict[str, Dict[str, str]],
+    ):
+        """P1.13: yield ``(kind, name, class_id)`` for every assignment whose
+        right-hand side constructs a known in-repo class.
+
+        ``kind`` is ``"local"`` for ``x = ClassName(...)`` and ``"self"`` for
+        ``self.x = ClassName(...)`` / ``cls.x = ...``. Nested function bodies
+        are not descended (their locals belong to the inner scope).
+        """
+        stack = [body]
+        while stack:
+            n = stack.pop()
+            if n.type == "function_definition" and n is not body:
+                continue
+            if n.type == "assignment":
+                left = n.child_by_field_name("left")
+                right = n.child_by_field_name("right")
+                if left is not None and right is not None:
+                    cls_id = self._infer_value_class(
+                        right, source, module_name, import_map, by_module_symbol
+                    )
+                    if cls_id is not None:
+                        if left.type == "identifier":
+                            yield "local", source[
+                                left.start_byte:left.end_byte
+                            ].decode("utf-8", errors="replace"), cls_id
+                        elif left.type == "attribute":
+                            obj = left.child_by_field_name("object")
+                            attr = left.child_by_field_name("attribute")
+                            if (obj is not None and attr is not None
+                                    and obj.type == "identifier"
+                                    and source[
+                                        obj.start_byte:obj.end_byte
+                                    ].decode("utf-8", errors="replace")
+                                    in self.config.receiver_self_names):
+                                yield "self", source[
+                                    attr.start_byte:attr.end_byte
+                                ].decode("utf-8", errors="replace"), cls_id
+            stack.extend(n.children)
+
+    def _infer_value_class(
+        self, value_node, source: bytes, module_name: str,
+        import_map: Dict[str, str],
+        by_module_symbol: Dict[str, Dict[str, str]],
+    ) -> Optional[str]:
+        """P1.13: if ``value_node`` is a constructor call ``ClassName(...)`` /
+        ``module.ClassName(...)`` resolving to a CLASS node, return its id.
+
+        Returns None for any non-constructor RHS (calls to functions, literals,
+        names, subscripts) — so a wrongly-typed receiver is never invented.
+        """
+        if value_node is None or value_node.type != "call":
+            return None
+        fn = value_node.child_by_field_name("function")
+        if fn is None:
+            return None
+        cid: Optional[str] = None
+        if fn.type == "identifier":
+            name = source[fn.start_byte:fn.end_byte].decode("utf-8", errors="replace")
+            cid = by_module_symbol.get(module_name, {}).get(name)
+            if cid is None and name in import_map:
+                cid = (self.builder._lookup_qualified(import_map[name], by_module_symbol)
+                       or self.builder._node_for_dotted(import_map[name]))
+        elif fn.type == "attribute":
+            chain = self._flatten_attr_chain(fn, source)
+            if not chain:
+                return None
+            cid = self.builder._resolve_chain_root(
+                chain[0], module_name, import_map, by_module_symbol
+            )
+            for link in chain[1:]:
+                if cid is None:
+                    break
+                cid = self.builder._contains_child(cid, link)
+        if (cid is not None and cid in self.builder._nodes
+                and self.builder._nodes[cid].node_type == NodeType.CLASS):
+            return cid
+        return None
+
+    @staticmethod
+    def _flatten_attr_chain(fn_node, source: bytes) -> Optional[List[str]]:
+        """Flatten an `attribute` CST node into its dotted identifier chain.
+
+        ``User.objects.get`` → ``["User", "objects", "get"]``.
+        Returns None when any link is not a plain identifier (calls,
+        subscripts, awaits in the receiver) — those receivers are dynamic
+        and must not be resolved by name.
+        """
+        parts: List[str] = []
+        node = fn_node
+        while node is not None and node.type == "attribute":
+            attr_node = node.child_by_field_name("attribute")
+            if attr_node is None:
+                return None
+            parts.append(
+                source[attr_node.start_byte:attr_node.end_byte].decode("utf-8", errors="replace")
+            )
+            node = node.child_by_field_name("object")
+        if node is None or node.type != "identifier":
+            return None
+        parts.append(
+            source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        )
+        parts.reverse()
+        return parts
+
+    def _return_type_of(self, func_id: str) -> Optional[str]:
+        """P1.14: follow a FUNCTION node's RETURNS edge to its CLASS node id.
+
+        RETURNS edges (P1.8) are declared annotations resolved to a class at
+        confidence 1.0, emitted by ``resolve_relationships()`` before
+        ``resolve_calls()`` runs. Returns None when the function has no
+        class-typed return annotation.
+        """
+        if func_id not in self.builder.graph:
+            return None
+        for _, tgt, d in self.builder.graph.out_edges(func_id, data=True):
+            if d.get("type") != EdgeType.RETURNS.name:
+                continue
+            n = self.builder._nodes.get(tgt)
+            if n is not None and n.node_type == NodeType.CLASS:
+                return tgt
+        return None
+
+    def _resolve_return_type_chain(
+        self, fn_node, source: bytes, module_name: str,
+        enclosing_class: Optional[str], import_map: Dict[str, str],
+        by_simple_name: Dict[str, List[str]],
+        by_module_symbol: Dict[str, Dict[str, str]],
+        param_types: Dict[str, str], getattr_class_ids: Set[str],
+        local_var_types: Dict[str, str],
+        self_attr_types: Dict[str, Dict[str, str]],
+    ):
+        """P1.14: resolve `f(...).a.b()` where the receiver root is a *call*.
+
+        Flatten the trailing attribute links, resolve the leading call's
+        callable, derive its receiver class (declared return type via
+        ``_return_type_of``, or the class itself when the leading call is a
+        constructor), then walk the remaining links and resolve the final
+        method. Annotation/constructor-gated — never over-approximates a
+        dynamic receiver (P1.7). Returns the standard
+        ``(target, confidence, edge_override)`` triple.
+        """
+        parts: List[str] = []
+        node = fn_node
+        while node is not None and node.type == "attribute":
+            attr_node = node.child_by_field_name("attribute")
+            if attr_node is None:
+                return None, 0.0, None
+            parts.append(
+                source[attr_node.start_byte:attr_node.end_byte].decode(
+                    "utf-8", errors="replace"
+                )
+            )
+            node = node.child_by_field_name("object")
+        if node is None or node.type != "call":
+            return None, 0.0, None
+        parts.reverse()
+        if not parts:
+            return None, 0.0, None
+
+        # Resolve the leading call's callable (handles self.f(), f(), mod.f(),
+        # and nested f().g() via recursion).
+        func_id, _conf, _edge = self._resolve_target(
+            node, source, module_name, enclosing_class, import_map,
+            by_simple_name, by_module_symbol, param_types,
+            getattr_class_ids, local_var_types, self_attr_types,
+        )
+        if not isinstance(func_id, str):
+            return None, 0.0, None  # ambiguous list or unresolved
+        target = self.builder._nodes.get(func_id)
+        if target is None:
+            return None, 0.0, None
+        if target.node_type == NodeType.CLASS:
+            cls_id: Optional[str] = func_id      # Foo().bar() — receiver = Foo
+        else:
+            cls_id = self._return_type_of(func_id)
+        if cls_id is None or cls_id not in self.builder._nodes:
+            return None, 0.0, None
+
+        *links, attr = parts
+        current = cls_id
+        for link in links:
+            typed = self_attr_types.get(current, {}).get(link)
+            if typed is not None and typed in self.builder._nodes:
+                current = typed
+                continue
+            nxt = self.builder._contains_child(current, link)
+            if nxt is None:
+                return None, 0.0, None
+            current = nxt
+        tid = self.builder._contains_child(current, attr) or \
+            self.builder._find_method_on_ancestors(current, attr)
+        if tid:
+            return tid, 0.85, None
+        return None, 0.0, None
+
+    # ------------------------------------------------------------------ CST utilities
+
+    @staticmethod
+    def _cst_scope_chain(node, source: bytes) -> List[str]:
+        """P2.17/P1.10: walk CST ancestors collecting class/function def names,
+        outermost first, with ``LOCALS_MARKER`` after every function segment.
+        """
+        chain: List[str] = []
+        p = node.parent
+        while p is not None:
+            if p.type in ("class_definition", "function_definition"):
+                nn = p.child_by_field_name("name")
+                if nn is not None:
+                    if p.type == "function_definition":
+                        # reversed below: marker must follow the function name
+                        chain.append(LOCALS_MARKER)
+                    chain.append(
+                        source[nn.start_byte:nn.end_byte].decode("utf-8", errors="replace")
+                    )
+            p = p.parent
+        chain.reverse()
+        return chain
+
+    def _iter_func_cst(self, root, source: bytes, module_name: str):
+        """Yield (function_definition CST node, node_id) for every function in file.
+
+        P2.17: uses the full scope chain (class + function ancestors) so that
+        two closures with the same name in different outer functions resolve to
+        the correct distinct graph node IDs.
+        """
+        stack = [root]
+        while stack:
+            node = stack.pop()
+            if node.type == "function_definition":
+                name_node = node.child_by_field_name("name")
+                if name_node:
+                    fname = source[name_node.start_byte:name_node.end_byte].decode(
+                        "utf-8", errors="replace"
+                    )
+                    scope_chain = self._cst_scope_chain(node, source)
+                    if scope_chain:
+                        nid = f"{module_name}:{'.'.join(scope_chain)}.{fname}"
+                    else:
+                        nid = f"{module_name}:{fname}"
+                    yield node, nid
+            stack.extend(node.children)
+
+    @staticmethod
+    def _collect_calls(body) -> List:
+        """Collect every `call` CST node under `body`."""
+        out = []
+        stack = [body]
+        while stack:
+            node = stack.pop()
+            if node.type == "call":
+                out.append(node)
+            # Don't descend into nested function bodies — those calls belong to the inner func
+            if node.type == "function_definition" and node is not body:
+                continue
+            stack.extend(node.children)
+        return out
+
+    # ------------------------------------------------------------------ P2.13
+    # Function-local callable-dict dispatch with variable aliasing.
+    # Handles the idiomatic router/command-table pattern that module-level
+    # mechanism 1 misses:
+    #     dispatch = {"a": self.h.handle_a, ...}   # local dict, bound-method vals
+    #     fn = dispatch.get(name)                  # var alias of a dict value
+    #     fn(args)                                 # call through the alias
+    # incl. the values being typed-attribute chains (`self.h.handle_a`) and the
+    # call living in a nested closure (cross-scope via node-id prefix).
+
+    @staticmethod
+    def _collect_module_literal_containers(root_node, source: bytes):
+        """Walk module-level assignments for literal dict/list/tuple containers.
+
+        Returns ``(dicts, refs)`` where:
+        - ``dicts``: ``{var_name: {str_key: identifier_name}}`` — dict literals
+          with string keys and bare-identifier values.
+        - ``refs``: ``{var_name: [identifier_names]}`` — ALL identifier values
+          inside any literal container (dict/list/tuple), for REFERENCES widening.
+        """
+        dicts: Dict[str, Dict[str, str]] = {}
+        refs: Dict[str, List[str]] = {}
+
+        def _text(n) -> str:
+            return source[n.start_byte:n.end_byte].decode("utf-8", errors="replace")
+
+        def _str_val(n) -> Optional[str]:
+            if n.type != "string":
+                return None
+            t = _text(n)
+            for q in ('"""', "'''", '"', "'"):
+                if t.startswith(q) and t.endswith(q) and len(t) > 2 * len(q):
+                    return t[len(q):-len(q)]
+            return None
+
+        def _ids_in(container) -> List[str]:
+            out: List[str] = []
+            stack = list(container.children)
+            while stack:
+                n = stack.pop()
+                if n.type == "identifier":
+                    out.append(_text(n))
+                elif n.type in ("dictionary", "list", "tuple", "pair"):
+                    stack.extend(n.children)
+            return out
+
+        for child in root_node.children:
+            node = child
+            if node.type == "expression_statement":
+                assigns = [c for c in node.children if c.type == "assignment"]
+                node = assigns[0] if assigns else None
+            if node is None or node.type != "assignment":
+                continue
+            lhs = node.child_by_field_name("left")
+            rhs = node.child_by_field_name("right")
+            if lhs is None or rhs is None or lhs.type != "identifier":
+                continue
+            var = _text(lhs)
+            if rhs.type == "dictionary":
+                pairs: Dict[str, str] = {}
+                all_ids: List[str] = []
+                for pair in rhs.children:
+                    if pair.type != "pair":
+                        continue
+                    kn = pair.child_by_field_name("key")
+                    vn = pair.child_by_field_name("value")
+                    if kn is None or vn is None:
+                        continue
+                    key_str = _str_val(kn)
+                    if key_str is not None and vn.type == "identifier":
+                        pairs[key_str] = _text(vn)
+                    if vn.type == "identifier":
+                        all_ids.append(_text(vn))
+                if pairs:
+                    dicts[var] = pairs
+                if all_ids:
+                    refs[var] = all_ids
+            elif rhs.type in ("list", "tuple"):
+                ids = [_text(c) for c in rhs.children if c.type == "identifier"]
+                if ids:
+                    refs[var] = ids
+        return dicts, refs
+
+    @staticmethod
+    def _iter_body_assignments(body):
+        """Yield every ``assignment`` CST node under ``body`` without descending
+        into nested function bodies (their assignments belong to the inner scope)."""
+        stack = [body]
+        while stack:
+            n = stack.pop()
+            if n.type == "function_definition" and n is not body:
+                continue
+            if n.type == "assignment":
+                yield n
+            stack.extend(n.children)
+
+    @staticmethod
+    def _attr_chain_parts(node, source: bytes) -> Optional[List[str]]:
+        """Flatten a pure identifier/attribute chain into dotted parts.
+
+        ``self.handlers.handle_scan`` → ``["self", "handlers", "handle_scan"]``.
+        Returns ``None`` for anything that is not a plain attribute/name chain
+        (calls, subscripts, etc.)."""
+        parts: List[str] = []
+        cur = node
+        while cur is not None:
+            if cur.type == "identifier":
+                parts.append(source[cur.start_byte:cur.end_byte].decode(
+                    "utf-8", errors="replace"))
+                break
+            if cur.type == "attribute":
+                attr = cur.child_by_field_name("attribute")
+                obj = cur.child_by_field_name("object")
+                if attr is None or obj is None:
+                    return None
+                parts.append(source[attr.start_byte:attr.end_byte].decode(
+                    "utf-8", errors="replace"))
+                cur = obj
+            else:
+                return None
+        parts.reverse()
+        return parts or None
+
+    def _resolve_callable_value(
+        self, value_node, source: bytes, module_name: str,
+        enclosing_class: Optional[str], import_map: Dict[str, str],
+        by_simple: Dict[str, List[str]], by_mod_sym: Dict[str, Dict[str, str]],
+        strict: bool = False,
+    ) -> Optional[str]:
+        """Resolve a dict *value* / alias-RHS expression to a callable node id.
+
+        Mirrors the typed-attribute hop in ``_resolve_target`` so bound-method
+        references (``self.handlers.handle_scan``) resolve via P1.13's
+        ``self_attr_types`` — not just bare/dotted names.
+
+        ``strict=True`` (P2.23) resolves a bare identifier RHS *only* against the
+        same-module top-level symbol table — never the fuzzy import-map /
+        unique-name fallback in ``_resolve_name``. The fallback mis-resolves
+        function-local ``import ... as x`` rebindings: e.g. click's
+        ``_getchar = f`` where two ``from … import … as f`` lines collide in the
+        module import map. Multi-link chains are already structural either way."""
+        parts = self._attr_chain_parts(value_node, source)
+        if not parts:
+            return None
+        if len(parts) == 1:
+            tid = by_mod_sym.get(module_name, {}).get(parts[0])
+            if tid is None and not strict:
+                tid = self.builder._resolve_name(
+                    parts[0], module_name, import_map, by_simple, by_mod_sym,
+                    strict=False,
+                )
+            return tid
+        attr = parts[-1]
+        links = parts[1:-1]
+        self_attr_types = self._self_attr_types
+        if parts[0] in self.config.receiver_self_names and enclosing_class:
+            current: Optional[str] = f"{module_name}:{enclosing_class}"
+        else:
+            current = self.builder._resolve_chain_root(
+                parts[0], module_name, import_map, by_mod_sym,
+            )
+        if current is None or current not in self.builder._nodes:
+            return None
+        for link in links:
+            typed = self_attr_types.get(current, {}).get(link)
+            if typed is not None and typed in self.builder._nodes:
+                current = typed
+                continue
+            nxt = self.builder._contains_child(current, link)
+            if nxt is None:
+                return None
+            current = nxt
+        return self.builder._contains_child(current, attr) or \
+            self.builder._find_method_on_ancestors(current, attr)
+
+    def _collect_local_callable_dicts(
+        self, body, source: bytes, module_name: str,
+        enclosing_class: Optional[str], import_map: Dict[str, str],
+        by_simple: Dict[str, List[str]], by_mod_sym: Dict[str, Dict[str, str]],
+    ) -> Dict[str, List[str]]:
+        """``{var_name: [callable_node_id, ...]}`` for dict literals in ``body``
+        whose values resolve to in-repo callables."""
+        out: Dict[str, List[str]] = {}
+        for n in self._iter_body_assignments(body):
+            left = n.child_by_field_name("left")
+            right = n.child_by_field_name("right")
+            if (left is None or right is None
+                    or left.type != "identifier" or right.type != "dictionary"):
+                continue
+            targets: List[str] = []
+            for pair in right.children:
+                if pair.type != "pair":
+                    continue
+                vn = pair.child_by_field_name("value")
+                if vn is None:
+                    continue
+                tid = self._resolve_callable_value(
+                    vn, source, module_name, enclosing_class,
+                    import_map, by_simple, by_mod_sym,
+                )
+                if (tid and tid in self.builder._nodes
+                        and not self.builder._is_denied(self.builder._nodes[tid].name)
+                        and tid not in targets):
+                    targets.append(tid)
+            if targets:
+                var = source[left.start_byte:left.end_byte].decode(
+                    "utf-8", errors="replace")
+                out.setdefault(var, [])
+                for t in targets:
+                    if t not in out[var]:
+                        out[var].append(t)
+        return out
+
+    def _collect_local_callable_aliases(
+        self, body, source: bytes, module_name: str,
+        enclosing_class: Optional[str], import_map: Dict[str, str],
+        by_simple: Dict[str, List[str]], by_mod_sym: Dict[str, Dict[str, str]],
+    ) -> Dict[str, List[str]]:
+        """P2.23: ``{var_name: [callable_node_id, ...]}`` for plain callable
+        re-bindings ``fn = <name>`` / ``fn = <attr.chain>`` in ``body`` whose RHS
+        resolves *structurally* to an in-repo function/class. A later
+        ``fn(args)`` is then dispatched to each (the conditional-rebind idiom
+        ``Cls = A if c else B; Cls()`` — values from every branch are kept).
+
+        Strict resolution is mandatory (see ``_resolve_callable_value`` strict):
+        the fuzzy fallback mis-resolves function-local ``import … as x``
+        rebindings and produces wrong edges. A missing edge beats a wrong one
+        (P1.7). RHS shapes that are calls/subscripts (``D.get(k)`` / ``D[k]`` /
+        ``factory()``) are left to mechanism 6 / the dynamic marker."""
+        out: Dict[str, List[str]] = {}
+        for n in self._iter_body_assignments(body):
+            left = n.child_by_field_name("left")
+            right = n.child_by_field_name("right")
+            if (left is None or right is None
+                    or left.type != "identifier"
+                    or right.type not in ("identifier", "attribute")):
+                continue
+            tid = self._resolve_callable_value(
+                right, source, module_name, enclosing_class,
+                import_map, by_simple, by_mod_sym, strict=True,
+            )
+            if (tid and tid in self.builder._nodes
+                    and self.builder._nodes[tid].node_type in (
+                        NodeType.FUNCTION, NodeType.CLASS)
+                    and not self.builder._is_denied(self.builder._nodes[tid].name)):
+                var = source[left.start_byte:left.end_byte].decode(
+                    "utf-8", errors="replace")
+                out.setdefault(var, [])
+                if tid not in out[var]:
+                    out[var].append(tid)
+        return out
+
+    def _collect_dict_aliases(
+        self, body, source: bytes, visible_names: Set[str],
+    ) -> Dict[str, str]:
+        """``{alias_var: dict_var}`` for ``h = D.get(k)`` / ``h = D[k]`` where
+        ``D`` is a known callable-dict."""
+        out: Dict[str, str] = {}
+        for n in self._iter_body_assignments(body):
+            left = n.child_by_field_name("left")
+            right = n.child_by_field_name("right")
+            if left is None or right is None or left.type != "identifier":
+                continue
+            dict_var: Optional[str] = None
+            if right.type == "call":
+                fn = right.child_by_field_name("function")
+                if fn is not None and fn.type == "attribute":
+                    obj = fn.child_by_field_name("object")
+                    meth = fn.child_by_field_name("attribute")
+                    if (obj is not None and obj.type == "identifier"
+                            and meth is not None
+                            and source[meth.start_byte:meth.end_byte].decode(
+                                "utf-8", errors="replace") == "get"):
+                        name = source[obj.start_byte:obj.end_byte].decode(
+                            "utf-8", errors="replace")
+                        if name in visible_names:
+                            dict_var = name
+            elif right.type == "subscript":
+                val = right.child_by_field_name("value")
+                if val is not None and val.type == "identifier":
+                    name = source[val.start_byte:val.end_byte].decode(
+                        "utf-8", errors="replace")
+                    if name in visible_names:
+                        dict_var = name
+            if dict_var:
+                alias_var = source[left.start_byte:left.end_byte].decode(
+                    "utf-8", errors="replace")
+                out[alias_var] = dict_var
+        return out
+
+    @staticmethod
+    def _extract_fstring_prefix(node, source: bytes) -> Optional[str]:
+        """Return the literal prefix from an f-string, e.g. ``f"handle_{x}"`` → ``"handle_"``.
+
+        Returns ``None`` when node is not an f-string or has no literal content
+        before the first interpolation.
+        """
+        if node.type not in ("string", "concatenated_string"):
+            return None
+        text = source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        lower = text.lower()
+        for marker in ('f"""', "f'''", 'f"', "f'"):
+            if lower.startswith(marker):
+                inner = text[len(marker):]
+                brace = inner.find("{")
+                if brace > 0:
+                    return inner[:brace]
+                break
+        return None
+
+    @staticmethod
+    def _nth_pos_arg(args_node, n: int):
+        """Return the n-th positional argument CST node (0-indexed)."""
+        if args_node is None:
+            return None
+        pos = 0
+        for child in args_node.children:
+            if child.type in (",", "(", ")"):
+                continue
+            if child.type in ("keyword_argument", "dictionary_splat_argument",
+                               "list_splat_argument"):
+                continue
+            if pos == n:
+                return child
+            pos += 1
+        return None
+
+    def harvest_literal_candidates(
+        self,
+        parses: Dict[Path, ParseResult],
+        results: Dict[Path, AnalysisResult],
+    ) -> int:
+        """P2.13: emit low-confidence candidate edges recovered from literal strings.
+
+        Mechanisms (all use ``metadata={"dispatch": "..."}`` on the edge):
+        1. **Dict dispatch** — ``_D = {k: fn}; _D[x]()`` → CALLS to each literal
+           value fn, confidence 0.6.
+        2. **getattr prefix** — ``getattr(self, f"pfx_{v}")`` → CALLS to each
+           class method whose name starts with the literal prefix, confidence 0.5.
+        3. **__init_subclass__ registry** — ``Base._reg[k]()`` where ``Base``
+           defines ``__init_subclass__`` → CALLS (INSTANTIATES for classes) to
+           each INHERITS subclass, confidence 0.6.
+        4. **importlib prefix** — ``import_module(f"pkg.{v}")`` → IMPORTS to
+           each matching module node, confidence 0.5.
+        5. **REFERENCES widening** — module-level ``{k: fn}``/``[fn]`` literals
+           → REFERENCES from the container VARIABLE to fn, confidence 0.9
+           (blast radius of fn includes the dispatch container).
+        6. **Callable-dict dispatch with aliasing (P2.22)** — a *function-local*
+           dict of callables, looked up into a variable, then called through it:
+           ``D = {k: self.h.handle}; fn = D.get(x); fn()`` → CALLS to each
+           resolved value, confidence 0.5. Values may be typed-attribute chains
+           (``self.h.handle`` via P1.13) and the call may live in a nested
+           closure (cross-scope via node-id prefix). This is what connects an
+           entry-point route to the handlers it dispatches through a table.
+        7. **Direct callable alias (P2.23)** — a plain re-binding of a callable,
+           then a call through it: ``fn = handler; fn()`` or the conditional
+           idiom ``Cls = A if c else B; Cls()`` → CALLS/INSTANTIATES to each
+           structurally-resolved target, confidence 0.5. RHS resolved *strictly*
+           (same-module top-level / typed self.attr / import-rooted chain only)
+           so function-local ``import … as x`` rebindings never mis-resolve.
+
+        Hard rule: any non-literal input to the patterns above → no candidate,
+        fall through to the P2.12 low-confidence marker. A missing edge is
+        always better than a wrong one.
+        """
+        added = 0
+
+        # Shared name→node indices (same as resolve_calls uses)
+        by_simple: Dict[str, List[str]] = defaultdict(list)
+        by_mod_sym: Dict[str, Dict[str, str]] = defaultdict(dict)
+        var_by_mod: Dict[str, Dict[str, str]] = defaultdict(dict)
+        for nid, nd in self.builder._nodes.items():
+            if nd.language != "python":
+                continue
+            if nd.node_type in (NodeType.FUNCTION, NodeType.CLASS):
+                by_simple[nd.name].append(nid)
+                by_mod_sym[nd.module][nd.name] = nid
+            elif nd.node_type == NodeType.VARIABLE and not nd.contained_in:
+                var_by_mod[nd.module][nd.name] = nid
+
+        # Build __init_subclass__ base index:
+        # {base_class_id: [subclass_id, ...]} from existing INHERITS edges,
+        # filtered to only bases that actually define __init_subclass__.
+        init_subclass_bases: Set[str] = set()
+        for nid, nd in self.builder._nodes.items():
+            if nd.language != "python":
+                continue
+            if nd.node_type == NodeType.FUNCTION and nd.name == "__init_subclass__" \
+                    and nd.contained_in:
+                parent_id = f"{nd.module}:{nd.contained_in}"
+                if parent_id in self.builder._nodes:
+                    init_subclass_bases.add(parent_id)
+
+        subclass_of: Dict[str, List[str]] = defaultdict(list)
+        for edge in self.builder._edges:
+            if edge.edge_type == EdgeType.INHERITS:
+                subclass_of[edge.target].append(edge.source)
+
+        def _edge(src: str, tgt: str, etype: EdgeType, fp: str, line: int, conf: float) -> None:
+            nonlocal added
+            if src == tgt:
+                return
+            if (src, tgt, etype) in self.builder._edge_keys:
+                return
+            if src not in self.builder._nodes or tgt not in self.builder._nodes:
+                return
+            self.builder._add_edge(GraphEdge(
+                source=src, target=tgt, edge_type=etype,
+                file_path=fp, line=line, confidence=conf,
+            ))
+            added += 1
+
+        def _node_text(node, src: bytes) -> str:
+            return src[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+
+        for file_path, parse in parses.items():
+            result = results.get(file_path)
+            if result is None:
+                continue
+            module_name = self.builder._module_for_result(result)
+            import_map = self.builder._import_map_for(result, module_name)
+            source = parse.source_bytes
+            fp_str = str(file_path)
+
+            # Collect module-level literal containers
+            mod_dicts, mod_refs = self._collect_module_literal_containers(
+                parse.tree.root_node, source
+            )
+
+            # P2.22/P2.23: function-local callable-dict + direct-alias maps
+            # (pre-pass so a binding in an outer function is visible to calls in
+            # its nested closures).
+            func_dicts: Dict[str, Dict[str, List[str]]] = {}
+            func_aliases: Dict[str, Dict[str, List[str]]] = {}
+            for func_cst, caller_id in self._iter_func_cst(
+                parse.tree.root_node, source, module_name
+            ):
+                if caller_id not in self.builder._nodes:
+                    continue
+                ec = self.builder._nodes[caller_id].contained_in
+                fbody = func_cst.child_by_field_name("body")
+                if fbody is None:
+                    continue
+                dmap = self._collect_local_callable_dicts(
+                    fbody, source, module_name, ec, import_map,
+                    by_simple, by_mod_sym,
+                )
+                if dmap:
+                    func_dicts[caller_id] = dmap
+                amap = self._collect_local_callable_aliases(
+                    fbody, source, module_name, ec, import_map,
+                    by_simple, by_mod_sym,
+                )
+                if amap:
+                    func_aliases[caller_id] = amap
+
+            # 5. REFERENCES widening — container VARIABLE → FUNCTION/CLASS targets
+            for var_name, ref_names in mod_refs.items():
+                # container may be a VARIABLE node (e.g. _OPS) or a CLASS/FUNCTION
+                var_id = (
+                    var_by_mod.get(module_name, {}).get(var_name)
+                    or by_mod_sym.get(module_name, {}).get(var_name)
+                )
+                if var_id is None:
+                    continue
+                for ref_name in ref_names:
+                    if ref_name in self.config.receiver_self_names or self.builder._is_denied(ref_name):
+                        continue
+                    fn_id = by_mod_sym.get(module_name, {}).get(ref_name)
+                    if fn_id is None:
+                        continue
+                    if self.builder._nodes[fn_id].node_type not in (NodeType.FUNCTION, NodeType.CLASS):
+                        continue
+                    _edge(var_id, fn_id, EdgeType.REFERENCES, fp_str, 0, 0.9)
+
+            # Walk each function body for call-site harvesting
+            for func_cst, caller_id in self._iter_func_cst(
+                parse.tree.root_node, source, module_name
+            ):
+                if caller_id not in self.builder._nodes:
+                    continue
+                enclosing_class = self.builder._nodes[caller_id].contained_in
+                body = func_cst.child_by_field_name("body")
+                if body is None:
+                    continue
+
+                # P2.22: callable-dicts visible here = own + ancestor functions
+                # (a closure's id is prefixed by its enclosing function's id).
+                visible: Dict[str, List[str]] = {}
+                for cid, dmap in func_dicts.items():
+                    if cid == caller_id or caller_id.startswith(cid + "."):
+                        visible.update(dmap)
+                aliases = (
+                    self._collect_dict_aliases(body, source, set(visible))
+                    if visible else {}
+                )
+                # P2.23: direct callable aliases, same cross-scope visibility.
+                visible_aliases: Dict[str, List[str]] = {}
+                for cid, amap in func_aliases.items():
+                    if cid == caller_id or caller_id.startswith(cid + "."):
+                        visible_aliases.update(amap)
+
+                for call_node in self._collect_calls(body):
+                    fn_node = call_node.child_by_field_name("function")
+                    if fn_node is None:
+                        continue
+                    line = call_node.start_point[0] + 1
+
+                    # 6. Callable-dict dispatch (P2.22): `D[k]()` on a local dict
+                    # or `fn(args)` where `fn = D.get(k)` / `fn = D[k]`.
+                    if visible:
+                        disp_targets: Optional[List[str]] = None
+                        if fn_node.type == "subscript":
+                            sv = fn_node.child_by_field_name("value")
+                            if sv is not None and sv.type == "identifier":
+                                nm = _node_text(sv, source)
+                                if nm in visible:
+                                    disp_targets = visible[nm]
+                        elif fn_node.type == "identifier":
+                            nm = _node_text(fn_node, source)
+                            if nm in aliases:
+                                disp_targets = visible.get(aliases[nm])
+                        if disp_targets:
+                            for tid in disp_targets:
+                                nd = self.builder._nodes.get(tid)
+                                if nd is None:
+                                    continue
+                                etype = (
+                                    EdgeType.INSTANTIATES
+                                    if nd.node_type == NodeType.CLASS
+                                    else EdgeType.CALLS
+                                )
+                                _edge(caller_id, tid, etype, fp_str, line, 0.5)
+                                if etype == EdgeType.CALLS:
+                                    self.builder._nodes[caller_id].calls.add(tid)
+                                    self.builder._nodes[tid].called_by.add(caller_id)
+
+                    # 7. Direct callable alias (P2.23): `fn = callable; fn()`.
+                    # RHS resolved structurally (strict) in the pre-pass, so this
+                    # only fires on in-repo functions/classes — incl. the
+                    # conditional-rebind idiom `Cls = A if c else B; Cls()`.
+                    if visible_aliases and fn_node.type == "identifier":
+                        nm = _node_text(fn_node, source)
+                        for tid in visible_aliases.get(nm, []):
+                            nd = self.builder._nodes.get(tid)
+                            if nd is None:
+                                continue
+                            etype = (
+                                EdgeType.INSTANTIATES
+                                if nd.node_type == NodeType.CLASS
+                                else EdgeType.CALLS
+                            )
+                            _edge(caller_id, tid, etype, fp_str, line, 0.5)
+                            if etype == EdgeType.CALLS:
+                                self.builder._nodes[caller_id].calls.add(tid)
+                                self.builder._nodes[tid].called_by.add(caller_id)
+
+                    # 1. Dict dispatch: _D[k]()
+                    if fn_node.type == "subscript":
+                        sub_val = fn_node.child_by_field_name("value")
+                        if sub_val is None:
+                            continue
+
+                        if sub_val.type == "identifier":
+                            # Local dict literal lookup
+                            var_name = _node_text(sub_val, source)
+                            for val_name in mod_dicts.get(var_name, {}).values():
+                                fn_id = by_mod_sym.get(module_name, {}).get(val_name)
+                                if fn_id is None:
+                                    fn_id = self.builder._resolve_name(
+                                        val_name, module_name, import_map,
+                                        by_simple, by_mod_sym, strict=False,
+                                    )
+                                if not fn_id:
+                                    continue
+                                nd = self.builder._nodes.get(fn_id)
+                                if nd is None:
+                                    continue
+                                etype = (
+                                    EdgeType.INSTANTIATES
+                                    if nd.node_type == NodeType.CLASS
+                                    else EdgeType.CALLS
+                                )
+                                _edge(caller_id, fn_id, etype, fp_str, line, 0.6)
+                                if etype == EdgeType.CALLS:
+                                    self.builder._nodes[caller_id].calls.add(fn_id)
+                                    self.builder._nodes[fn_id].called_by.add(caller_id)
+
+                        elif sub_val.type == "attribute":
+                            # 3. __init_subclass__: Base._registry[k]()
+                            attr_obj = sub_val.child_by_field_name("object")
+                            if attr_obj is not None and attr_obj.type == "identifier":
+                                base_name = _node_text(attr_obj, source)
+                                base_id = by_mod_sym.get(module_name, {}).get(base_name)
+                                if base_id is None:
+                                    base_id = self.builder._resolve_name(
+                                        base_name, module_name, import_map,
+                                        by_simple, by_mod_sym, strict=True,
+                                    )
+                                if base_id and base_id in init_subclass_bases:
+                                    for sub_id in subclass_of.get(base_id, []):
+                                        nd = self.builder._nodes.get(sub_id)
+                                        if nd is None:
+                                            continue
+                                        etype = (
+                                            EdgeType.INSTANTIATES
+                                            if nd.node_type == NodeType.CLASS
+                                            else EdgeType.CALLS
+                                        )
+                                        _edge(caller_id, sub_id, etype, fp_str, line, 0.6)
+
+                    else:
+                        fn_text = _node_text(fn_node, source)
+
+                        # 2. getattr prefix: getattr(self, f"pfx_{v}")
+                        if fn_text == "getattr" and enclosing_class:
+                            args = call_node.child_by_field_name("arguments")
+                            first = self._nth_pos_arg(args, 0)
+                            second = self._nth_pos_arg(args, 1)
+                            if first is not None and second is not None:
+                                first_text = _node_text(first, source)
+                                if first_text in self.config.receiver_self_names:
+                                    prefix = self._extract_fstring_prefix(second, source)
+                                    if prefix:
+                                        class_id = f"{module_name}:{enclosing_class}"
+                                        for _, child_id, d in self.builder.graph.out_edges(
+                                            class_id, data=True
+                                        ):
+                                            if d.get("type") != EdgeType.CONTAINS.name:
+                                                continue
+                                            child = self.builder._nodes.get(child_id)
+                                            if child is None or child.node_type != NodeType.FUNCTION:
+                                                continue
+                                            if child.name.startswith(prefix):
+                                                _edge(caller_id, child_id, EdgeType.CALLS, fp_str, line, 0.5)
+                                                self.builder._nodes[caller_id].calls.add(child_id)
+                                                self.builder._nodes[child_id].called_by.add(caller_id)
+
+                        # 4. importlib prefix: import_module(f"pkg.{v}")
+                        elif fn_text in ("importlib.import_module", "__import__"):
+                            args = call_node.child_by_field_name("arguments")
+                            mod_arg = self._nth_pos_arg(args, 0)
+                            if mod_arg is not None:
+                                prefix = self._extract_fstring_prefix(mod_arg, source)
+                                if prefix:
+                                    pkg_prefix = prefix.rstrip(".")
+                                    source_mod_id = module_name
+                                    for nid, nnd in self.builder._nodes.items():
+                                        if nnd.language != "python":
+                                            continue
+                                        if nnd.node_type != NodeType.MODULE:
+                                            continue
+                                        if nid == pkg_prefix or nid.startswith(pkg_prefix + "."):
+                                            _edge(source_mod_id, nid, EdgeType.IMPORTS,
+                                                  fp_str, line, 0.5)
+
+        return added