adl-toolkit 0.0.0-stage → 0.1.3

package/adl_drift/lang/java/resolution/overloads.py

@@ -0,0 +1,1275 @@
+"""Java overload selection: member lookup, applicability, and ranking."""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Callable, Dict, FrozenSet, List, Optional, Set, Tuple, Union
+
+from adl_drift.graph.edges import EdgeType
+from adl_drift.graph.node import NodeType
+from adl_drift.lang.java.ids import erased_type
+from adl_drift.lang.java.resolution.constants import (
+    JAVA_EXTERNAL_SUBTYPE_STUBS,
+    JAVA_EXTERNAL_TYPES,
+    JAVA_LANG_SIMPLE_TYPES,
+    _JAVA_FUNCTIONAL_INTERFACE_SHAPE,
+    _JAVA_FUNCTIONAL_INTERFACES,
+    _LAMBDA_ARG_TYPE,
+    _NULL_ARG_TYPE,
+    _UNKNOWN_ARG_TYPE,
+    argument_nodes,
+)
+from adl_drift.lang.java.resolution.model import (
+    ImportContext as _ImportContext,
+    LocalScopes as _LocalScopes,
+)
+
+
+class OverloadResolutionMixin:
+    def _lexical_outer_class_ids(self, class_id: str) -> List[str]:
+        """Nearest-to-farthest source classes lexically enclosing `class_id`."""
+        if ":" not in class_id:
+            return []
+        module, qualname = class_id.rsplit(":", 1)
+        parts = qualname.split(".")
+        out: List[str] = []
+        for end in range(len(parts) - 1, 0, -1):
+            candidate = f"{module}:{'.'.join(parts[:end])}"
+            node = self.builder._nodes.get(candidate)
+            if node is not None and node.node_type == NodeType.CLASS:
+                out.append(candidate)
+        return out
+
+    def _top_level_class_id(self, class_id: str) -> str:
+        """The outermost lexically-enclosing class id for `class_id`
+        (itself, if already top-level). JLS 6.6.1: a `private` member is
+        accessible anywhere within the body of the *top level* class that
+        encloses its declaration — not merely from its own literal
+        declaring class — so a nested class may freely call a `private`
+        method of its enclosing class (and vice versa, and sibling nested
+        classes of one another) as long as both share the same top-level
+        ancestor. `_lexical_outer_class_ids` is nearest-to-farthest, so the
+        last entry is the farthest (top-level) one."""
+        outers = self._lexical_outer_class_ids(class_id)
+        return outers[-1] if outers else class_id
+
+    def _contains_children(self, node_id: str) -> List[str]:
+        """Every node directly `CONTAINS`-ed by `node_id` (class members,
+        module classes, ...). Memoized per `node_id` (`_contains_children_cache`,
+        reset alongside `_declared_direct_ancestors`/`_class_ancestors_cache`
+        at the start of every resolution pass): every CONTAINS edge, including
+        generated member stubs, is fully established before call-site
+        resolution starts (`_build_resolution_indexes`) and never changes
+        mid-pass, yet this was called 480K times on JUnit5 with a fresh
+        NetworkX `out_edges` traversal every time — fix #5, same shape as
+        fix #4's `_direct_ancestors` (§8 bước 7 profiling: this was the
+        largest remaining self-time entry after fix #3+#4 landed)."""
+        cached = self._contains_children_cache.get(node_id)
+        if cached is not None:
+            return cached
+        if node_id not in self.builder.graph:
+            result: List[str] = []
+        else:
+            result = [
+                t for _, t, d in self.builder.graph.out_edges(node_id, data=True)
+                if d.get("type") == EdgeType.CONTAINS.name
+            ]
+        self._contains_children_cache[node_id] = result
+        return result
+
+    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 `graph/builder.py` wires from
+        `Symbol.scope_chain` (`f"{module}:{'.'.join(chain)}"`).
+
+        Unlike `GraphNode.contained_in` — which `extractor.py::
+        _find_parent_class` deliberately keeps as the coarser *nearest
+        enclosing simple name* ("Box"), by its own docstring a separate,
+        coarser field than the scope-chain uniqueness key — this is
+        qualified even for a nested class ("Outer.Box"), so it actually
+        matches how `_class_type_params`/INHERITS/IMPLEMENTS class ids are
+        keyed (both built off the same scope-chain-qualified node ids).
+        A bare `f"{module}:{contained_in}"` lookup silently misses for any
+        nested class member (F-01)."""
+        cache = self._declaring_class_cache
+        if cache is not None and member_id in cache:
+            return cache[member_id]
+        result = self._declaring_class_id_uncached(member_id)
+        if cache is not None:
+            cache[member_id] = result
+        return result
+
+    def _declaring_class_id_uncached(self, member_id: str) -> Optional[str]:
+        if member_id not in self.builder.graph:
+            return None
+        for source, _, data in self.builder.graph.in_edges(member_id, data=True):
+            if data.get("type") != EdgeType.CONTAINS.name:
+                continue
+            source_node = self.builder._nodes.get(source)
+            if source_node is not None and source_node.node_type == NodeType.CLASS:
+                return source
+        # Methods inside an anonymous class have a synthetic scope segment
+        # (`Outer.$1.method()`), but no standalone CLASS node for `$1`, so the
+        # shared builder cannot attach a CONTAINS edge to that immediate
+        # scope. Recover the nearest real lexical type from the qualified
+        # member id. This is also what Java uses to resolve an unqualified
+        # nested type such as `Keys` inside an enum-constant body.
+        member = self.builder._nodes.get(member_id)
+        if member is None:
+            return None
+        prefix = f"{member.module}:"
+        if not member_id.startswith(prefix) or "(" not in member_id:
+            return None
+        method_head = member_id[len(prefix):].rsplit("(", 1)[0]
+        if "." not in method_head:
+            return None
+        owner = method_head.rsplit(".", 1)[0]
+        while owner:
+            candidate = f"{member.module}:{owner}"
+            node = self.builder._nodes.get(candidate)
+            if node is not None and node.node_type == NodeType.CLASS:
+                return candidate
+            if "." not in owner:
+                break
+            owner = owner.rsplit(".", 1)[0]
+        return None
+
+    def _direct_ancestors(self, class_id: str, edge_type: EdgeType) -> List[str]:
+        # `_declared_direct_ancestors` is fully populated before any call site
+        # resolution runs (orchestration.py's `_build_resolution_indexes`), so
+        # checking it first never changes which branch below is taken — it
+        # only skips the expensive NetworkX out_edges traversal on every one
+        # of the millions of calls this makes where the cache already has the
+        # answer (P0 profiling: this line was ~22% of JUnit5 resolve_calls
+        # time before the reorder, almost entirely wasted work on cache hits).
+        key = (class_id, edge_type)
+        if key in self._declared_direct_ancestors:
+            return self._declared_direct_ancestors[key]
+        # Graph-only fallback supports partial/incremental graphs whose
+        # declaring AnalysisResult was unavailable to this resolver pass —
+        # in practice this is every external/JDK class_id, since only
+        # project source classes get an entry above. Without a supporting
+        # AnalysisResult these edges cannot change mid-pass, so the result is
+        # written back into the same dict once computed: bottleneck #4
+        # profiling (JAVA_PERFORMANCE_OPTIMIZATION_PLAN.md §8 bước 7) found
+        # ~79% of all _direct_ancestors calls on JUnit5 missed the cache and
+        # re-walked NetworkX's out_edges for the same handful of common
+        # external ancestors (Object, Comparable, ...) millions of times.
+        if class_id not in self.builder.graph:
+            result: List[str] = []
+        else:
+            edge_type_name = edge_type.name
+            result = [
+                t for _, t, d in self.builder.graph.out_edges(class_id, data=True)
+                if d.get("type") == edge_type_name
+            ]
+        self._declared_direct_ancestors[key] = result
+        return result
+
+    def _class_ancestors(self, class_id: str) -> List[str]:
+        """BFS over INHERITS ∪ IMPLEMENTS, nearest first — a class's own
+        superclass and interfaces before their own ancestors in turn.
+
+        Memoized per class_id (`_class_ancestors_cache`, reset alongside
+        `_declared_direct_ancestors` at the start of every resolution pass in
+        `_build_resolution_indexes`): the INHERITS/IMPLEMENTS edges this BFS
+        walks are fully established before call-site resolution starts and
+        never change mid-pass, yet this was called 748K times on JUnit5 for a
+        graph of only ~3.7K classes — the same class's ancestor chain
+        recomputed from scratch on almost every call (§8 bước 7 profiling).
+        """
+        cached = self._class_ancestors_cache.get(class_id)
+        if cached is not None:
+            return cached
+        seen: Set[str] = {class_id}
+        q: deque = deque(
+            self._direct_ancestors(class_id, EdgeType.INHERITS)
+            + self._direct_ancestors(class_id, EdgeType.IMPLEMENTS)
+        )
+        out: List[str] = []
+        while q:
+            cur = q.popleft()
+            if cur in seen:
+                continue
+            seen.add(cur)
+            out.append(cur)
+            q.extend(self._direct_ancestors(cur, EdgeType.INHERITS))
+            q.extend(self._direct_ancestors(cur, EdgeType.IMPLEMENTS))
+        self._class_ancestors_cache[class_id] = out
+        return out
+
+    def _all_field_types(self, class_id: str) -> Dict[str, str]:
+        """`{field_name: declared_type_text}` for `class_id`, merged with
+        every INHERITS/IMPLEMENTS ancestor's fields not shadowed by a
+        closer declaration — the field analogue of `_members_named`'s
+        own+ancestor merge, needed because `self._field_types` is keyed per
+        declaring class only (built once in `resolve_calls()` from each
+        field's own `contained_in`), so a field declared on an ancestor was
+        otherwise invisible to a subclass's `this.field.method()` chain."""
+        def declared_fields(owner_id: str) -> Dict[str, str]:
+            fields = dict(self._field_types.get(owner_id, {}))
+            owner = self.builder._nodes.get(owner_id)
+            if owner is not None:
+                # A record component declares a private final field even
+                # though there is no `field_declaration` CST node for the
+                # extractor to emit.  Treat compiler-mandated component
+                # fields exactly like explicit fields for bare/`this` and
+                # pattern-variable receiver chains.
+                fields.update(dict(owner.metadata.get("record_components", {})))
+            return fields
+
+        merged: Dict[str, str] = {}
+        for anc in reversed(self._class_ancestors(class_id)):
+            fields = declared_fields(anc)
+            # A field declared as `T ctx` on `Base<T>` is a `ClassCtx` on
+            # `Sub extends Base<ClassCtx>` (JLS 8.1.4 / 4.5): substitute the
+            # ancestor's class variables through the inheritance edge the
+            # same way method return types already are.
+            bindings = self._compose_type_var_bindings(class_id, [], anc)
+            if bindings:
+                fields = {
+                    name: self._replace_type_variables(text, bindings)
+                    for name, text in fields.items()
+                }
+            merged.update(fields)
+        merged.update(declared_fields(class_id))
+        return merged
+
+    def _visible_bare_field_types(self, class_id: str) -> Dict[str, str]:
+        """Fields visible to an unqualified name inside ``class_id``.
+
+        A non-static nested/local class may refer to fields of its lexical
+        enclosing instances without an explicit ``Outer.this`` qualifier.
+        Merge farthest-to-nearest lexical owners, then the current class, so
+        normal Java shadowing keeps the closest declaration. Explicit
+        ``this.field`` resolution deliberately continues to use
+        ``_all_field_types(class_id)`` and therefore cannot accidentally bind
+        an outer-instance field.
+        """
+        current = self.builder._nodes.get(class_id)
+        if current is not None and "static" in current.metadata.get("modifiers", ()):
+            return self._all_field_types(class_id)
+        accessible_outers: List[str] = []
+        for outer_id in self._lexical_outer_class_ids(class_id):
+            accessible_outers.append(outer_id)
+            outer = self.builder._nodes.get(outer_id)
+            if outer is not None and "static" in outer.metadata.get("modifiers", ()):
+                break
+        merged: Dict[str, str] = {}
+        for outer_id in reversed(accessible_outers):
+            merged.update(self._all_field_types(outer_id))
+        merged.update(self._all_field_types(class_id))
+        return merged
+
+    def _erased_signature(self, func_id: str) -> Tuple[str, ...]:
+        """Erased positional parameter-type tuple, used to tell a true
+        override (same name + same erased signature) apart from an overload
+        (same name, different signature) when merging inherited members.
+
+        Memoized per `func_id` (`_erased_signature_cache`, reset alongside
+        the other per-run caches in `_build_resolution_indexes`): purely a
+        function of `_param_type_lists[func_id]`, which is fixed for the
+        whole resolution pass, yet `_members_named` recomputes it for every
+        candidate on every lookup — a large overload family (e.g. a
+        project's own `assertEquals`-shaped API with dozens of siblings)
+        gets looked up at every call site sharing that name, so the same
+        handful of func_ids' signatures were being re-erased tens of
+        thousands of times before this cache."""
+        cache = getattr(self, "_erased_signature_cache", None)
+        if cache is not None:
+            cached = cache.get(func_id)
+            if cached is not None:
+                return cached
+        sig = tuple(erased_type(t) for t in self._param_type_lists.get(func_id, []))
+        if cache is not None:
+            cache[func_id] = sig
+        return sig
+
+    def _members_named(
+        self, class_id: str, name: str, search_ancestors: bool, search_self: bool = True,
+        exclude_constructors: bool = False, caller_class_id: Optional[str] = None,
+    ) -> List[str]:
+        """Every FUNCTION child of `class_id` named `name`, plus — iff
+        `search_ancestors` — every same-named overload across the *entire*
+        INHERITS/IMPLEMENTS ancestor chain, not just the nearest ancestor
+        tier that declares one: a name declared two-or-more levels up
+        (`Child extends Parent extends GrandParent`) stays a candidate as
+        long as no *closer* class (own class, or a nearer ancestor already
+        walked) overrides it with an identical erased signature — that's a
+        true override and hides it; a differently-signed overload does not,
+        and both must stay candidates for `_select_overload`. When
+        `search_self` is False, the own class is never consulted, not even
+        for override exclusion — this is `super.m()`'s path, which must
+        always reach an ancestor's method regardless of the child's own
+        override.
+
+        A Java constructor's node is named after its class's own simple
+        name, so a plain `method_invocation` lookup for a method that
+        happens to share the class's name (e.g. implementing an interface
+        method named `Foo` inside a class also named `Foo`) would otherwise
+        be indistinguishable from the constructor. `exclude_constructors`
+        drops any candidate flagged `metadata["constructor"]`; callers that
+        deliberately look up a class's own name to find its constructor(s)
+        (`new T(...)`, `this(...)`, `super(...)`) leave it False."""
+        def is_visible(candidate_id: str) -> bool:
+            if caller_class_id is None:
+                return True
+            node = self.builder._nodes.get(candidate_id)
+            if node is None or "private" not in node.metadata.get("modifiers", ()):
+                return True
+            declaring = self._declaring_class_id(candidate_id)
+            if declaring is None:
+                return True
+            return self._top_level_class_id(declaring) == self._top_level_class_id(
+                caller_class_id,
+            )
+
+        own = [
+            c for c in self._function_members_named(class_id, name)
+            if not (exclude_constructors and self.builder._nodes[c].metadata.get("constructor"))
+            and is_visible(c)
+        ]
+        if not search_ancestors:
+            return own if search_self else []
+        collected: List[str] = list(own) if search_self else []
+        shadowed = {self._erased_signature(c) for c in collected}
+        for anc in self._class_ancestors(class_id):
+            for c in self._function_members_named(anc, name):
+                n = self.builder._nodes[c]
+                if exclude_constructors and n.metadata.get("constructor"):
+                    continue
+                if not is_visible(c):
+                    continue
+                sig = self._erased_signature(c)
+                if sig in shadowed:
+                    continue
+                collected.append(c)
+                shadowed.add(sig)
+        return collected
+
+    def _function_members_named(self, class_id: str, name: str) -> List[str]:
+        """FUNCTION children of `class_id` named `name`, in `_contains_children`
+        order. Built once per class from `_contains_children` (same source of
+        truth `_members_named` scanned linearly on every call) and memoized in
+        `_members_by_name_cache`, reset with the other per-run caches."""
+        cache = self._members_by_name_cache
+        index = cache.get(class_id) if cache is not None else None
+        if index is None:
+            index = {}
+            for c in self._contains_children(class_id):
+                n = self.builder._nodes.get(c)
+                if n is not None and n.node_type == NodeType.FUNCTION:
+                    index.setdefault(n.name, []).append(c)
+            if cache is not None:
+                cache[class_id] = index
+        return index.get(name, ())
+
+    def _arity_matches(self, func_id: str, arg_count: int) -> bool:
+        types = self._param_type_lists.get(func_id, [])
+        if len(types) == arg_count:
+            return True
+        if types and self._is_vararg_param(types[-1]):
+            # varargs-shaped last param accepts >= the fixed-arity prefix.
+            return arg_count >= len(types) - 1
+        return False
+
+    def _is_vararg_candidate(self, func_id: str) -> bool:
+        """True iff `func_id`'s *last* declared parameter is a true vararg
+        (`T...`), i.e. this candidate can only be reached in JLS's phase-3
+        "variable arity invocation" — never in phase 1/2 fixed-arity form
+        except the single "array form" case `_param_types_match`/
+        `_param_types_compatible` already special-case. Used by
+        `_select_overload` to keep phase-3-only candidates from competing
+        with a phase-1/2-applicable fixed-arity sibling — see there."""
+        raw_types = self._param_type_lists.get(func_id, [])
+        return bool(raw_types) and self._is_vararg_param(raw_types[-1])
+
+    def _is_phase3_only(
+        self, func_id: str, arg_types: List[str], arg_ctx: "_ImportContext",
+    ) -> bool:
+        """True iff, *for this particular call*, `func_id` is reachable only
+        through JLS §15.12.2 phase 3 (variable-arity, element-wise vararg
+        expansion) — and so must not compete with a phase-1/2-applicable
+        sibling. Unlike `_is_vararg_candidate`, which classifies purely by
+        declaration shape (`T...`), this is invocation-form-aware: a
+        vararg-declaring method still has a phase-1/2 *array form* (JLS
+        §15.12.2.1) when the caller passes exactly the declared arity with a
+        final argument assignable to the vararg parameter's array type
+        (`m(String[] arr)` against `m(String...)`), and in that form it is a
+        legitimate phase-1/2 candidate, not a phase-3-only one.
+
+        A fixed-arity candidate is never phase-3-only. A vararg candidate is
+        phase-3-only unless the call matches its array form — i.e. the arg
+        count differs from the declared parameter count (element-wise
+        expansion is the only fit), or the single trailing argument is not
+        `_types_compatible` with the vararg array type (`save(1)` against
+        `save(int...)`: `int` is not assignable to `int[]`, so array form
+        fails and this stays phase 3, preserving the P4.4 regression fix that
+        lets a `save(long)` sibling win). The array-form gate mirrors the
+        array-form branch `_param_types_match`/`_param_types_compatible`
+        already special-case, using the loosest phase (`allow_boxing=True`)
+        so classification never *under*-includes a candidate those two
+        methods would still accept in a tier."""
+        if not self._is_vararg_candidate(func_id):
+            return False
+        types = [erased_type(t) for t in self._param_type_lists.get(func_id, [])]
+        if len(arg_types) != len(types):
+            return True
+        param_ctx = self._param_ctx_for(func_id)
+        vararg_type = types[-1]
+        trailing = arg_types[len(types) - 1:]
+        if len(trailing) == 1 and self._types_compatible(
+            vararg_type, trailing[0], param_ctx, arg_ctx, allow_boxing=True,
+        ):
+            return False  # array form: a phase-1/2 candidate for this call.
+        return True
+
+    @staticmethod
+    def _is_vararg_param(raw_type_text: str) -> bool:
+        """True iff the *source* declaration used `T...`, not a plain `T[]`.
+
+        Must check the raw (pre-erasure) text: `erased_type()` normalizes
+        `...` to `[]` for type-identity purposes, which would otherwise make
+        a plain array-typed last parameter (`Object[] rows`, exactly one
+        argument required) indistinguishable from true varargs
+        (`Object... rows`, zero-or-more arguments) — the two accept
+        different call-site arities and must not be conflated here.
+        """
+        return raw_type_text.strip().endswith("...")
+
+    # JLS 5.1.2 widening primitive conversion: a value of the key type may be
+    # passed where any type in the value set is declared.
+    _PRIMITIVE_WIDENING: Dict[str, FrozenSet[str]] = {
+        "byte": frozenset({"short", "int", "long", "float", "double"}),
+        "short": frozenset({"int", "long", "float", "double"}),
+        "char": frozenset({"int", "long", "float", "double"}),
+        "int": frozenset({"long", "float", "double"}),
+        "long": frozenset({"float", "double"}),
+        "float": frozenset({"double"}),
+    }
+    # JLS 5.1.7/5.1.8 boxing/unboxing conversion, checked in both directions.
+    _BOXED_PRIMITIVE: Dict[str, str] = {
+        "int": "Integer", "long": "Long", "double": "Double", "float": "Float",
+        "boolean": "Boolean", "char": "Character", "byte": "Byte", "short": "Short",
+    }
+    # Reverse of `_BOXED_PRIMITIVE` (wrapper -> primitive), used to unbox an
+    # arg type before checking primitive widening — see `_types_compatible`.
+    _UNBOXED_PRIMITIVE: Dict[str, str] = {v: k for k, v in _BOXED_PRIMITIVE.items()}
+
+    @staticmethod
+    def _external_type_name(type_name: str, ctx: "_ImportContext") -> Optional[str]:
+        """Exact FQN of an external (JDK) type spelled in `ctx`, or None.
+
+        An explicit import, a wildcard import matching an exact-FQN hierarchy
+        fact, and the implicit `java.lang` names qualify; an already dotted
+        spelling is kept as written. A name that resolves to nothing here is
+        *not* guessed."""
+        wildcard_matches = {
+            f"{package}.{type_name}" for package in ctx.wildcard_packages
+            if f"{package}.{type_name}" in JAVA_EXTERNAL_TYPES
+        }
+        if len(wildcard_matches) == 1:
+            return next(iter(wildcard_matches))
+        if "." in type_name:
+            head, tail = type_name.split(".", 1)
+            imported_head = ctx.import_map.get(head)
+            if imported_head is not None:
+                return f"{imported_head}.{tail}"
+            return type_name
+        imported = ctx.import_map.get(type_name)
+        if imported is not None:
+            return imported
+        if "java.util" in ctx.wildcard_packages and type_name in {
+            "ArrayList", "Collection", "HashMap", "HashSet", "List", "Map", "Set", "TreeMap",
+        }:
+            return f"java.util.{type_name}"
+        if type_name in JAVA_LANG_SIMPLE_TYPES:
+            return f"java.lang.{type_name}"
+        return None
+
+    def _types_compatible(
+        self, param_type: str, arg_type: str,
+        param_ctx: "_ImportContext", arg_ctx: "_ImportContext",
+        allow_boxing: bool = True,
+    ) -> bool:
+        """True iff a value statically typed `arg_type` (erased, per
+        `_infer_arg_types`) may be passed where `param_type` (also erased)
+        is declared: exact match, `Object` (every reference/boxed-primitive
+        type is Object-compatible), JLS 5.1.2 primitive widening, JLS
+        5.1.7/5.1.8 boxing/unboxing, or — for two types that resolve to
+        in-repo CLASS nodes — an INHERITS/IMPLEMENTS subtype relationship
+        (a subclass argument passed where a superclass/interface parameter
+        is declared, the single most common source of "known type, but not
+        an exact match" in real Java). Reference arrays follow JLS widening
+        reference conversion component-wise (`String[]` -> `Object[]`, and
+        source `Child[]` -> `Parent[]`). Array-ness must agree before that
+        recursion; primitive array components never box or widen into a
+        different component type (`int[]` is not `Object[]` or `long[]`).
+
+        `param_type` and `arg_type` are resolved against *separate*
+        contexts on purpose: `param_type` was written in the candidate
+        method's own declaring file and must resolve against that file's
+        imports/wildcard-imports (`param_ctx`), while `arg_type` was
+        written at the call site and resolves against the caller's
+        (`arg_ctx`) — using the caller's context for both, or dropping
+        wildcard-imported packages entirely, silently fails to resolve a
+        wildcard-imported or cross-file-imported type and drops an
+        otherwise-valid candidate (P4.4 regression fix).
+
+        `allow_boxing` splits JLS §15.12.2's phases: with it False (phase 1,
+        strict invocation) only identity + primitive widening + reference
+        widening/subtyping apply — *no* boxing/unboxing; with it True (phase
+        2, loose invocation) boxing/unboxing is additionally allowed.
+        `_select_overload` tries the strict phase across all candidates before
+        the loose one, so an `int` argument picks a `save(long)` (widening,
+        phase 1) over a `save(Integer)` (boxing, phase 2) sibling the way
+        real javac does, instead of fanning out to both.
+
+        The `null` literal (`_NULL_ARG_TYPE`) is compatible with every
+        *reference* parameter type (class, interface, array, boxed
+        primitive) and no primitive — independent of `allow_boxing`, since
+        `null` -> reference is a widening reference conversion (phase 1).
+
+        JLS 5.1.8 unboxing, optionally followed by 5.1.2 widening, is also
+        modeled: a wrapper arg (`Integer`) unboxes to its primitive
+        (`int`) and, if that alone doesn't match `param_type`, is checked
+        against `_PRIMITIVE_WIDENING` from there — `Integer` -> `long`
+        (F-05 fix). The reverse chain (box, then widen as a *primitive*) is
+        not attempted because JLS doesn't allow it: once boxed, only
+        widening *reference* conversion applies, which the
+        `_resolve_declared_type`/`_class_ancestors` path below already
+        covers.
+
+        Still not modeled (documented simplification): external/JDK
+        supertypes (`Comparable` param + `String` arg needs a JDK hierarchy
+        this issue doesn't fabricate). A pair neither rule proves compatible
+        is treated as a real mismatch,
+        not an unknown — the caller drops the candidate. When more than one
+        candidate is compatible, `_select_overload` calls `_most_specific`
+        to rank them (JLS §15.12.2.5) before falling back to a fan-out —
+        see that method."""
+        if arg_type == _NULL_ARG_TYPE:
+            # null type: assignable to any reference (anything not a
+            # primitive), never to a primitive parameter.
+            return param_type not in self._BOXED_PRIMITIVE
+        if arg_type.startswith(_LAMBDA_ARG_TYPE):
+            simple = erased_type(param_type).split(".")[-1]
+            if simple in _JAVA_FUNCTIONAL_INTERFACES:
+                shape = _JAVA_FUNCTIONAL_INTERFACE_SHAPE.get(simple)
+                lambda_shape = arg_type[len(_LAMBDA_ARG_TYPE) + 1:] if (
+                    len(arg_type) > len(_LAMBDA_ARG_TYPE)
+                ) else None
+                if shape is not None and lambda_shape is not None:
+                    count_text, _, value_shape = lambda_shape.partition(":")
+                    if count_text.isdigit() and int(count_text) != shape[0]:
+                        # JLS 15.27.3: a lambda's declared parameter count
+                        # must exactly equal its target SAM's arity — not
+                        # merely "compatible" the way widening/boxing works
+                        # for an ordinary value argument.
+                        return False
+                    if value_shape == "value" and shape[1]:
+                        # A block body proven to contain a value `return` is
+                        # not void-compatible (JLS 15.27.2): it cannot
+                        # target a void-returning SAM like Runnable/Consumer.
+                        return False
+                return True
+            # Project-declared SAM interfaces are valid lambda targets too
+            # (`Converter<T>` in Commons CLI). Resolve strictly in the
+            # candidate parameter's declaring context and require exactly
+            # one abstract instance-method signature across its hierarchy.
+            param_id = self._resolve_declared_type(
+                param_type, param_ctx.module, param_ctx.import_map,
+                param_ctx.wildcard_packages, param_ctx.enclosing_class_id,
+            )
+            if param_id is None:
+                return False
+            param_node = self.builder._nodes.get(param_id)
+            if param_node is None or param_node.metadata.get("java_type_kind") != "interface":
+                return False
+            abstract_signatures: Set[Tuple[str, str]] = set()
+            for owner_id in (param_id, *self._class_ancestors(param_id)):
+                if owner_id not in self.builder.graph:
+                    continue
+                for _, member_id, data in self.builder.graph.out_edges(owner_id, data=True):
+                    if data.get("type") != EdgeType.CONTAINS.name:
+                        continue
+                    member = self.builder._nodes.get(member_id)
+                    if (
+                        member is not None
+                        and member.node_type == NodeType.FUNCTION
+                        and member.metadata.get("java_is_abstract")
+                        and not member.metadata.get("java_is_static")
+                    ):
+                        abstract_signatures.add((member.name, member.signature or ""))
+            if len(abstract_signatures) == 1:
+                return True
+            if abstract_signatures:
+                return False
+            # `interface TimeoutProvider extends Function<Config, R> {}`
+            # declares nothing itself; it is functional exactly when its
+            # single external super-interface is a JDK functional one.
+            return self._external_functional_super(param_id) is not None
+        if param_type == arg_type:
+            return True
+        arg_is_primitive = arg_type in self._BOXED_PRIMITIVE
+        if param_type == "Object":
+            # `String` -> `Object` is a widening reference conversion
+            # (phase 1); `int` -> `Object` needs boxing first (phase 2).
+            return (not arg_is_primitive) or allow_boxing
+        param_is_array = param_type.endswith("[]")
+        arg_is_array = arg_type.endswith("[]")
+        if param_is_array or arg_is_array:
+            if not (param_is_array and arg_is_array):
+                return False
+            param_component = param_type[:-2]
+            arg_component = arg_type[:-2]
+            primitive_types = set(self._BOXED_PRIMITIVE)
+            if param_component in primitive_types or arg_component in primitive_types:
+                return param_component == arg_component
+            return self._types_compatible(
+                param_component, arg_component, param_ctx, arg_ctx,
+                allow_boxing=False,
+            )
+        if param_type in self._PRIMITIVE_WIDENING.get(arg_type, ()):
+            return True
+        if allow_boxing:
+            boxed_arg = self._BOXED_PRIMITIVE.get(arg_type)
+            boxed_param = self._BOXED_PRIMITIVE.get(param_type)
+            if boxed_arg == param_type or boxed_param == arg_type:
+                return True
+            unboxed_arg = self._UNBOXED_PRIMITIVE.get(arg_type)
+            if unboxed_arg is not None and param_type in self._PRIMITIVE_WIDENING.get(unboxed_arg, ()):
+                return True  # unboxing (5.1.8) then widening (5.1.2): Integer -> int -> long.
+        external_name = self._external_type_name
+
+        param_external = external_name(param_type, param_ctx)
+        arg_external = external_name(arg_type, arg_ctx)
+        if param_external is not None and param_external == arg_external:
+            return True
+        if (
+            param_external is not None
+            and arg_external is not None
+            and (arg_external, param_external) in JAVA_EXTERNAL_SUBTYPE_STUBS
+        ):
+            return True
+        param_id = self._resolve_declared_type(
+            param_type, param_ctx.module, param_ctx.import_map, param_ctx.wildcard_packages,
+            param_ctx.enclosing_class_id,
+        )
+        arg_id = self._resolve_declared_type(
+            arg_type, arg_ctx.module, arg_ctx.import_map, arg_ctx.wildcard_packages,
+            arg_ctx.enclosing_class_id,
+        )
+        if param_id is not None and arg_id is not None:
+            return param_id == arg_id or param_id in self._class_ancestors(arg_id)
+        if param_external is not None and arg_id is not None:
+            # A source class reaches an external supertype through its own
+            # `extends` clause or through any source ancestor's: the exact
+            # JDK facts apply to the nearest external superclass on that
+            # chain (`NoTestsDiscoveredException extends JUnitException
+            # extends RuntimeException` may be passed as `Throwable`).  Each
+            # `extends` spelling resolves in its own declaring file.
+            for owner_id in (arg_id, *self._class_ancestors(arg_id)):
+                owner_node = self.builder._nodes.get(owner_id)
+                owner_ctx = (
+                    self._file_ctx.get(owner_node.file_path)
+                    if owner_node is not None else None
+                )
+                if owner_node is None or owner_ctx is None:
+                    continue
+                declared_supers = (
+                    *owner_node.metadata.get("java_superclass_args", ()),
+                    *owner_node.metadata.get("java_implements_args", ()),
+                )
+                for declared_super in declared_supers:
+                    super_name = external_name(erased_type(declared_super), owner_ctx)
+                    if super_name is None:
+                        continue
+                    if (
+                        super_name == param_external
+                        or (super_name, param_external) in JAVA_EXTERNAL_SUBTYPE_STUBS
+                    ):
+                        return True
+        return False
+
+    def _external_functional_super(self, interface_id: str) -> Optional[Tuple[str, str]]:
+        """`(owner_id, extends_text)` when `interface_id` (or a source ancestor)
+        extends exactly one external JDK functional interface, else None.
+
+        The extends clause is resolved in its own declaring file: the name
+        must not be a source class there, and its exact FQN must be the JDK
+        one (`java.util.function.Function`, `java.lang.Runnable`, ...).  A
+        project interface that declares its own abstract method is handled
+        by the caller before this is consulted."""
+        found: List[Tuple[str, str]] = []
+        for owner_id in (interface_id, *self._class_ancestors(interface_id)):
+            owner_node = self.builder._nodes.get(owner_id)
+            owner_ctx = (
+                self._file_ctx.get(owner_node.file_path)
+                if owner_node is not None else None
+            )
+            if owner_node is None or owner_ctx is None:
+                continue
+            if owner_node.metadata.get("java_type_kind") != "interface":
+                continue
+            for declared_super in owner_node.metadata.get("java_superclass_args", ()):
+                raw = erased_type(declared_super).strip()
+                if raw.rsplit(".", 1)[-1] not in _JAVA_FUNCTIONAL_INTERFACES:
+                    continue
+                if self._resolve_declared_type(
+                    raw, owner_ctx.module, owner_ctx.import_map,
+                    owner_ctx.wildcard_packages,
+                ) is not None:
+                    continue
+                external = self._external_type_name(raw, owner_ctx)
+                if external is None or not external.startswith("java."):
+                    continue
+                found.append((owner_id, declared_super))
+        return found[0] if len(found) == 1 else None
+
+    def _narrower_or_equal(
+        self, a_type: str, b_type: str,
+        a_ctx: "_ImportContext", b_ctx: "_ImportContext",
+    ) -> bool:
+        """True iff every value accepted where `a_type` is declared is also
+        accepted where `b_type` is declared — i.e. `a_type` is at least as
+        specific as `b_type`. Used only to rank *pairs of already-compatible
+        candidates'* declared parameter types against each other (see
+        `_most_specific`), not to re-derive compatibility with a concrete
+        argument — that is `_types_compatible`'s job. Primitive widening
+        via the existing `_PRIMITIVE_WIDENING` lattice; reference types via
+        an INHERITS/IMPLEMENTS subtype check, each side resolved against
+        its *own* declaring context (`a_ctx`/`b_ctx` — two overloads being
+        ranked against each other may be declared in two different files,
+        same reasoning as `_types_compatible`'s `param_ctx`/`arg_ctx`
+        split). Array types and primitive/reference mixed pairs are
+        deliberately not ordered (same "not modeled" boundary
+        `_types_compatible` documents for boxing/unboxing chains) — an
+        unordered pair returns `False` in both directions, which only
+        costs a tie-break (both stay fan-out candidates), never a wrong
+        pick."""
+        if a_type == b_type:
+            return True
+        if a_type.endswith("[]") or b_type.endswith("[]"):
+            return False
+        a_is_prim = a_type in self._BOXED_PRIMITIVE
+        b_is_prim = b_type in self._BOXED_PRIMITIVE
+        if a_is_prim and b_is_prim:
+            return b_type in self._PRIMITIVE_WIDENING.get(a_type, ())
+        if a_is_prim or b_is_prim:
+            return False
+        if b_type == "Object":
+            # Mirrors `_types_compatible`'s own `Object`-is-universal-
+            # supertype shortcut: `Object` is a JDK type this resolver
+            # never fabricates a CLASS node for, so `_resolve_declared_type`
+            # below would always return `None` for it and this domination
+            # would incorrectly read as "unorderable" instead of "any
+            # reference type is narrower than Object".
+            return True
+        a_id = self._resolve_declared_type(
+            a_type, a_ctx.module, a_ctx.import_map, a_ctx.wildcard_packages,
+        )
+        b_id = self._resolve_declared_type(
+            b_type, b_ctx.module, b_ctx.import_map, b_ctx.wildcard_packages,
+        )
+        if a_id is not None and b_id is not None:
+            return a_id == b_id or b_id in self._class_ancestors(a_id)
+        if a_id is None and b_id is None:
+            # Two external JDK parameter types are ordered by the same
+            # exact-FQN facts `_types_compatible` accepts, so a nested
+            # source return canonicalized to `java.util.Set` still prefers
+            # `m(Set)` over `m(Collection)`.
+            a_external = self._external_type_name(a_type, a_ctx)
+            b_external = self._external_type_name(b_type, b_ctx)
+            if a_external is not None and b_external is not None:
+                return (
+                    a_external == b_external
+                    or (a_external, b_external) in JAVA_EXTERNAL_SUBTYPE_STUBS
+                )
+        return False
+
+    def _dominates(self, c1: str, c2: str) -> bool:
+        """True iff `c1` is strictly more specific than `c2` — every one of
+        `c1`'s declared parameter types is narrower-or-equal to `c2`'s at
+        the same position, and at least one position is strictly narrower
+        (not just equal). Positional only: candidates with differing
+        parameter-list lengths (a fixed-arity/vararg shape mismatch between
+        two same-arg-count-compatible overloads) are treated as
+        incomparable rather than guessed at."""
+        types1 = [erased_type(t) for t in self._param_type_lists.get(c1, [])]
+        types2 = [erased_type(t) for t in self._param_type_lists.get(c2, [])]
+        if len(types1) != len(types2):
+            return False
+        ctx1 = self._param_ctx_for(c1)
+        ctx2 = self._param_ctx_for(c2)
+        strictly_narrower_somewhere = False
+        for t1, t2 in zip(types1, types2):
+            if not self._narrower_or_equal(t1, t2, ctx1, ctx2):
+                return False
+            if not self._narrower_or_equal(t2, t1, ctx2, ctx1):
+                strictly_narrower_somewhere = True
+        return strictly_narrower_somewhere
+
+    def _most_specific(self, candidates: List[str]) -> List[str]:
+        """Narrow a `compatible`-tier candidate set down to the maximally
+        specific ones — JLS §15.12.2.5's "most specific method" tie-break,
+        run only among candidates `_param_types_compatible` already
+        accepted (this never promotes an otherwise-incompatible candidate,
+        it only prunes redundant *compatible* ones). A candidate dominated
+        by another (see `_dominates`) is dropped; a pair `_dominates` can't
+        order — two interfaces neither extending the other, or a type this
+        resolver can't resolve — is a genuine tie and both survive, exactly
+        the fan-out behavior `_select_overload` had before this method
+        existed. `save(long)`/`save(float)` both declared, called with a
+        statically-known `int`: `save(long)` dominates `save(float)`
+        (`int` widens to both, but `long` also widens to `float` while
+        `float` does not widen to `long` — `long` is strictly narrower) and
+        survives alone."""
+        dominated: Set[str] = set()
+        for c1 in candidates:
+            for c2 in candidates:
+                if c1 != c2 and self._dominates(c1, c2):
+                    dominated.add(c2)
+        return [c for c in candidates if c not in dominated]
+
+    @staticmethod
+    def _vararg_component_type(vararg_array_type: str) -> str:
+        """`int[]` -> `int`, `String[]` -> `String` — the type each
+        variable-arity *element* must match, as opposed to the array type
+        itself (which only a caller passing the array directly, "array
+        form", needs to match — see `_param_types_match`/
+        `_param_types_compatible`)."""
+        return (
+            vararg_array_type[:-2]
+            if vararg_array_type.endswith("[]")
+            else vararg_array_type
+        )
+
+    def _param_types_match(self, func_id: str, arg_types: List[str]) -> bool:
+        """Exact erased-type match, positionally — JLS §15.12.2 "phase 1,
+        strict invocation" (no widening/boxing/subtyping). Preferred over
+        `_param_types_compatible` whenever it has any survivor: an argument
+        that exactly matches one overload's declared parameter type must
+        pick that overload even when a *different* overload would also
+        accept it via widening (`save(int)` and `save(long)` both declared,
+        `save(1)` must resolve only to `save(int)`, never fan out to
+        `save(long)` too) — mirrors javac's phase ordering, where a phase-1
+        applicable method always wins over a phase-2-only one.
+
+        A vararg-declaring candidate is checked as vararg-or-nothing, never
+        as a fixed-arity candidate first (P4.4 regression fix): `void
+        save(int... values)` erases to a single `int[]` parameter, so
+        checking `len(types) == len(arg_types)` first and comparing
+        `save(1)`'s `int` argument against the *array* type `int[]` fails
+        and used to `return` immediately — the vararg branch, which must
+        compare against the *component* type `int` instead, never ran.
+        Separately, the old vararg branch only checked the fixed prefix
+        length/content and never compared the vararg elements' types at
+        all, so any trailing argument type — `String...` called with two
+        `int`s — was silently accepted."""
+        raw_types = self._param_type_lists.get(func_id, [])
+        types = [erased_type(t) for t in raw_types]
+        method_type_params = self._method_type_param_bounds.get(func_id, {})
+
+        def exact_or_generic_array(param_type: str, arg_type: str) -> bool:
+            if param_type == arg_type:
+                return True
+            dimensions = 0
+            component = param_type
+            while component.endswith("[]"):
+                dimensions += 1
+                component = component[:-2]
+            if not dimensions or component not in method_type_params:
+                return False
+            arg_component = arg_type
+            for _ in range(dimensions):
+                if not arg_component.endswith("[]"):
+                    return False
+                arg_component = arg_component[:-2]
+            # `T` cannot be a primitive, so `T[]` never matches `int[]`.
+            return arg_component not in self._BOXED_PRIMITIVE
+
+        is_vararg = bool(raw_types) and self._is_vararg_param(raw_types[-1])
+        if not is_vararg:
+            return len(types) == len(arg_types) and all(
+                exact_or_generic_array(p, a) for p, a in zip(types, arg_types)
+            )
+        fixed = types[:-1]
+        if len(arg_types) < len(fixed) or arg_types[: len(fixed)] != fixed:
+            return False
+        trailing = arg_types[len(fixed):]
+        vararg_type = types[-1]
+        if len(trailing) == 1 and trailing[0] == vararg_type:
+            return True  # array form: caller passed the array itself.
+        component_type = self._vararg_component_type(vararg_type)
+        return all(a == component_type for a in trailing)
+
+    def _param_ctx_for(self, func_id: str) -> "_ImportContext":
+        """The `_ImportContext` of the file that declares `func_id` — its
+        parameter types were written against *that* file's imports and
+        wildcard-imports, not whichever call site is currently resolving
+        against it. Keyed by `GraphNode.file_path`, not `.module`: several
+        files commonly share one Java module (module id = declared
+        `package`), each with its own import list, so a module-keyed lookup
+        would silently pick an arbitrary same-package file's imports instead
+        of the declaring file's own. Falls back to an empty context (no
+        import binds, no wildcard packages, `module` still correct so
+        same-package resolution still works) if the file is somehow missing
+        from `self._file_ctx` — e.g. a single-file incremental rescan that
+        doesn't re-pass every file `results` normally covers — which only
+        drops cross-package import resolution for that one lookup, never
+        raises, matching this resolver's "missing edge over wrong edge"
+        precision stance.
+
+        Memoized per `func_id` (`_param_ctx_for_cache`, reset alongside the
+        other per-run caches): every input (`self._file_ctx`, `node.module`,
+        `_declaring_class_id(func_id)`) is fixed for the whole resolution
+        pass, but this is called once per candidate on every overload
+        applicability check, so the same heavily-overloaded method gets its
+        context rebuilt on every call site that names it."""
+        cache = getattr(self, "_param_ctx_for_cache", None)
+        if cache is not None:
+            cached = cache.get(func_id)
+            if cached is not None:
+                return cached
+        node = self.builder._nodes.get(func_id)
+        if node is None:
+            ctx = _ImportContext("", {}, [])
+        else:
+            ctx = self._file_ctx.get(node.file_path, _ImportContext(node.module, {}, []))
+            ctx = ctx._replace(enclosing_class_id=self._declaring_class_id(func_id))
+        if cache is not None:
+            cache[func_id] = ctx
+        return ctx
+
+    def _param_types_compatible(
+        self, func_id: str, arg_types: List[str], arg_ctx: "_ImportContext",
+        allow_boxing: bool = True, allow_method_type_inference: bool = False,
+    ) -> bool:
+        """Positional argument/parameter compatibility via
+        `_types_compatible`. `allow_boxing` selects the JLS §15.12.2 phase:
+        False = "phase 1, strict invocation" (identity, primitive widening,
+        reference subtyping — no boxing); True = "phase 2, loose invocation"
+        (adds boxing/unboxing). `_select_overload` tries the strict phase
+        across all candidates before the loose one — see there for why phase 1
+        must be exhausted before phase 2 is attempted.
+
+        `func_id`'s own declaring-file context (`_param_ctx_for`) resolves
+        its parameter types; `arg_ctx` (the call site's context) resolves
+        the argument types — see `_types_compatible` for why these must not
+        be conflated.
+
+        Vararg handling mirrors `_param_types_match` (P4.4 regression fix,
+        same bug, same shape): checked as vararg-or-nothing rather than
+        trying fixed-arity first, and every trailing ("variadic") argument
+        is checked against the vararg's *component* type via
+        `_types_compatible` — not silently accepted, and not compared
+        against the array type unless the caller actually passed exactly
+        one argument that is itself array-compatible (array form)."""
+        param_ctx = self._param_ctx_for(func_id)
+        raw_types = self._param_type_lists.get(func_id, [])
+        types = [erased_type(t) for t in raw_types]
+        method_type_params = self._method_type_param_bounds.get(func_id, {})
+
+        def compatible(param_type: str, arg_type: str) -> bool:
+            # `_UNKNOWN_ARG_TYPE` means "no information about this argument,"
+            # not a real type — it must never rule a candidate in or out, on
+            # any parameter shape (array, generic, primitive). Checked before
+            # every other branch below, each of which assumes `arg_type` is a
+            # real (possibly sentinel-but-known) type.
+            if arg_type == _UNKNOWN_ARG_TYPE:
+                return True
+            # A method inference variable accepts a reference argument without
+            # treating its short name as a source class. Primitive arguments
+            # require the loose-invocation (boxing) phase. This remains scoped
+            # to an already-found own/inherited candidate; it adds no global
+            # name lookup or candidate fan-out.
+            if allow_method_type_inference and param_type in method_type_params:
+                # A lambda needs a functional-interface target type. An
+                # unbounded inference variable (`<T> ... T value`) has the
+                # implicit bound Object and is not itself a lambda target.
+                # A variable explicitly bounded by a functional interface is
+                # valid; reuse the existing JDK/project SAM check for it.
+                if arg_type.startswith(_LAMBDA_ARG_TYPE):
+                    bound = method_type_params[param_type]
+                    if erased_type(bound) == "Object":
+                        return False
+                    return self._types_compatible(
+                        bound, arg_type, param_ctx, arg_ctx, allow_boxing,
+                    )
+                return arg_type not in self._BOXED_PRIMITIVE or allow_boxing
+            # Class-scoped variables are instantiated by the receiver
+            # (`Store<String>` makes `N` a reference type). The resolver does
+            # not yet carry that substitution into this overload helper, but
+            # treating the declared class variable as a reference slot is
+            # sound for applicability and lets generic field calls inside a
+            # lambda resolve without guessing a concrete source class.
+            owner = self._declaring_class_id(func_id)
+            if (
+                owner is not None
+                and param_type in self._class_type_params.get(owner, [])
+            ):
+                return arg_type not in self._BOXED_PRIMITIVE or allow_boxing
+            # Method type variables can occur inside an array type (`T[]`),
+            # not only as the complete parameter spelling.  Treat an array
+            # argument as an instantiation of that variable only when its
+            # dimensions agree and its component is a reference type.  This
+            # lets `T[] copy(T[] value)` win over a sibling `T copy(T value)`
+            # for a `Widget[]` argument; accepting the latter alone loses a
+            # real Java overload edge. Primitive arrays are excluded because
+            # a Java generic variable cannot be instantiated with `int`.
+            array_dims = 0
+            component = param_type
+            while component.endswith("[]"):
+                array_dims += 1
+                component = component[:-2]
+            if allow_method_type_inference and array_dims and component in method_type_params:
+                arg_component = arg_type
+                for _ in range(array_dims):
+                    if not arg_component.endswith("[]"):
+                        return False
+                    arg_component = arg_component[:-2]
+                if arg_component in self._BOXED_PRIMITIVE:
+                    return False
+                bound = method_type_params[component]
+                return self._types_compatible(
+                    bound, arg_component, param_ctx, arg_ctx, allow_boxing,
+                )
+            return self._types_compatible(
+                param_type, arg_type, param_ctx, arg_ctx, allow_boxing,
+            )
+
+        is_vararg = bool(raw_types) and self._is_vararg_param(raw_types[-1])
+        if not is_vararg:
+            if len(types) != len(arg_types):
+                return False
+            return all(
+                compatible(p, a)
+                for p, a in zip(types, arg_types)
+            )
+        fixed = types[:-1]
+        if len(arg_types) < len(fixed):
+            return False
+        if not all(
+            compatible(p, a)
+            for p, a in zip(fixed, arg_types[: len(fixed)])
+        ):
+            return False
+        trailing = arg_types[len(fixed):]
+        vararg_type = types[-1]
+        if len(trailing) == 1 and compatible(vararg_type, trailing[0]):
+            return True  # array form: caller passed the array itself.
+        component_type = self._vararg_component_type(vararg_type)
+        return all(
+            compatible(component_type, a)
+            for a in trailing
+        )
+
+    def _narrow_candidates_by_known_arg_types(
+        self, candidates: List[str], arg_count: int, args_node,
+        source: bytes, local_types: "_LocalScopes", param_types: Dict[str, str],
+        field_types: Dict[str, str], arg_ctx: "_ImportContext",
+    ) -> List[str]:
+        """Shrink an otherwise-total arity-only fan-out using whichever
+        argument positions *are* statically known, leaving a genuinely
+        unresolvable position as a wildcard rather than guessing it.
+
+        `_infer_arg_types`'s all-or-nothing contract (by design: never guess
+        an unknown argument) means one unresolvable position — commonly an
+        external/JDK method-call result with no exact-return fact, such as
+        `exception.getMessage()` — makes `_select_overload` fan out across
+        *every* same-arity candidate, even ones a known sibling argument
+        rules out entirely. `assertEquals(expectedMessage, exception.getMessage())`
+        (`expectedMessage` a plain `String`) is a real example: no
+        `assertEquals(byte,byte)`/`(int,int)`/…/`(Double,Double)` sibling can
+        ever accept a `String` first argument, so fanning out to all of
+        JUnit's ~20 primitive/boxed overloads is not "unresolved" for any of
+        them — it is a wrong edge for every one but the `(Object,Object)`
+        family. This reuses `_param_types_compatible`'s own vararg/generic/
+        boxing-aware applicability check with `_UNKNOWN_ARG_TYPE` standing in
+        for each position this function cannot determine, so an unresolvable
+        position can never disqualify a candidate — only a position with a
+        *real* known type can.
+
+        Per-position typing first tries `_infer_arg_type` (literals/
+        declarations only) and, only when that is None, falls back to
+        `_infer_known_arg_type_for_narrowing` — the same source/JDK
+        return-type propagation the `var`/fluent-chain typing already
+        trusts (batch 16 P5 finding #1: `exception.getMessage()` itself
+        stayed unknown before this, so a *known* sibling argument's type
+        could never exclude anything). This asymmetry with `_infer_arg_type`
+        is safe specifically because narrowing can only ever *exclude* a
+        same-arity sibling a resolved type provably cannot reach — it can
+        never fabricate an edge or select a sole winner from a chain-typed
+        guess the way using it for `_infer_arg_types`' exact-match path
+        could.
+
+        Returns `candidates` unchanged whenever no position is statically
+        known, arity is inconsistent with the call, or narrowing would
+        otherwise discard every candidate (a correctness backstop, not
+        expected in practice): this never changes behavior for a call this
+        helper cannot actually inform."""
+        if len(candidates) <= 1:
+            return candidates
+        arg_nodes = argument_nodes(args_node)
+        if len(arg_nodes) != arg_count:
+            return candidates
+        partial = [
+            self._infer_arg_type(node, source, local_types, param_types, field_types)
+            or self._infer_known_arg_type_for_narrowing(
+                node, source, arg_ctx, local_types, param_types, field_types,
+            )
+            for node in arg_nodes
+        ]
+        if all(t is None for t in partial):
+            return candidates
+        known_types = [
+            erased_type(t) if t is not None else _UNKNOWN_ARG_TYPE for t in partial
+        ]
+        survivors = [
+            candidate for candidate in candidates
+            if not self._arity_matches(candidate, arg_count)
+            or self._param_types_compatible(
+                candidate, known_types, arg_ctx, allow_method_type_inference=True,
+            )
+        ]
+        return survivors if survivors else candidates
+
+    def _select_overload(
+        self, candidates: List[str], arg_count: int,
+        arg_types: Optional[List[str]], conf_for: Callable[[str], float],
+        arg_ctx: "_ImportContext", allow_method_type_inference: bool = False,
+    ) -> Tuple[Union[str, List[str], None], float]:
+        """P4.4 overload selection: arg count first — arity is a hard Java
+        constraint, checked even for a single candidate, never skipped. When
+        arg types are statically known, arity-matching candidates are then
+        ranked in two tiers mirroring JLS §15.12.2's phases: exact erased-type
+        match (`_param_types_match`) first, and only when *no* candidate
+        exact-matches does the wider widening/boxing/subtype-aware
+        `_param_types_compatible` apply — and when more than one candidate
+        passes that check, `_most_specific` (JLS §15.12.2.5) prunes it down
+        to whichever candidate's parameter types are strictly narrower than
+        every other survivor's before falling back to a fan-out, so e.g.
+        `save(long)`/`save(float)` called with a statically-known `int`
+        resolves to `save(long)` alone rather than both. Each tier applies
+        the same rule after that ranking — one survivor resolves at full
+        confidence, more than one (a genuine tie `_most_specific` couldn't
+        order) fans out at reduced confidence, per-candidate confidence
+        still coming from `conf_for` — but a lone *exact* match is never
+        diluted by a widening-only sibling overload, and a lone *arity*
+        match is no longer accepted unconditionally the way it was before this fix: a
+        single candidate whose declared parameter types are provably
+        incompatible with the call's statically-known argument types (e.g.
+        `repo.save(1)` against a sole `Repo.save(String)`) is a real
+        mismatch, not an unresolved ambiguity, and resolves to nothing
+        rather than a wrong edge. No candidate matching the call's arg count
+        (or, when types are known, matching neither tier) is a resolution
+        failure: it must never fall back to a broader candidate set, which
+        would emit an edge to a same-name overload the call site cannot
+        actually reach. `conf_for` looks up the confidence tied to *where* a
+        given candidate was declared (own class vs. inherited), so a merged
+        own+ancestor candidate set (see `_members_named`) reports the right
+        confidence for whichever tier the winner actually came from.
+
+        **Non-vararg candidates are ranked, and given a chance to resolve
+        alone, before any vararg-declaring candidate is even considered**
+        (P4.4 regression fix): JLS §15.12.2 tries phase 1 (strict, no
+        boxing, no varargs) and phase 2 (loose — boxing/widening allowed,
+        still no varargs) across *every* applicable method — fixed-arity
+        and vararg-declared alike, the vararg one only in its unexpanded
+        "array form" — before ever attempting phase 3 (variable arity,
+        element-wise vararg expansion). A vararg-declared candidate reached
+        only via expansion is a phase-3-only candidate, and phase 3 must
+        never even be attempted while a phase-1/2-applicable method exists.
+        The two-tier exact-then-compatible ranking above conflated this:
+        `_param_types_match`'s vararg branch matches a *component* type
+        exactly (`save(int... v)` vs. `save(1)` matches `int` == `int`),
+        landing it in the same "exact" tier as a true fixed-arity exact
+        match, while a fixed-arity sibling reachable only through widening
+        (`save(long)` vs. the same `save(1)`) is relegated to the
+        "compatible" tier — `exact`'s existing short-circuit then resolved
+        to the vararg candidate alone, or fanned out to both, never letting
+        `save(long)` win the way real javac does. **Fix:** partition
+        `by_arity` into a phase-1/2 pool and a phase-3-only pool first, keyed
+        on `_is_phase3_only` — which is *invocation-form-aware*, not a
+        declaration-shape test: a vararg-declaring method reached in its
+        phase-1/2 *array form* for this call (`m(String[])` against
+        `m(String...)`) stays in the phase-1/2 pool and competes with a
+        fixed-arity sibling, while one reachable only through element-wise
+        expansion (`save(1)` against `save(int...)`, `int` not assignable to
+        `int[]`) is deferred to phase 3. This corrects the earlier
+        declaration-only `_is_vararg_candidate` partition, which demoted
+        *every* vararg candidate — array form and all — out of phase 1/2,
+        so an array-form call could never beat a widening-compatible
+        fixed-arity overload (`m(Object)`). Run the existing
+        exact-then-compatible-then-`_most_specific` ranking against the
+        phase-1/2 pool alone, and only fall through to ranking the
+        phase-3-only pool the same way if the first produced zero survivors
+        (nothing phase-1/2-applicable at all) — never merging the two pools'
+        results, and never touching `_param_types_match`/
+        `_param_types_compatible`/`_most_specific` themselves, which stay
+        correct within each pool."""
+        if not candidates:
+            return None, 0.0
+        by_arity = [c for c in candidates if self._arity_matches(c, arg_count)]
+        if not by_arity:
+            return None, 0.0
+        if arg_types is None:
+            if len(by_arity) == 1:
+                return by_arity[0], conf_for(by_arity[0])
+            return by_arity, min(min(conf_for(c) for c in by_arity), 0.55)
+
+        def _resolve_tier(hits: List[str]) -> Tuple[Union[str, List[str], None], float]:
+            """One survivor -> full confidence; >1 (a genuine tie
+            `_most_specific` couldn't order) -> fan out at reduced
+            confidence; 0 -> unresolved. Applied per phase tier below."""
+            if not hits:
+                return None, 0.0
+            if len(hits) > 1:
+                hits = self._most_specific(hits)
+            if len(hits) == 1:
+                return hits[0], conf_for(hits[0])
+            return hits, min(min(conf_for(c) for c in hits), 0.55)
+
+        def _rank(pool: List[str]) -> Tuple[Union[str, List[str], None], float]:
+            # JLS §15.12.2 phase ordering, stopping at the first phase with
+            # any applicable candidate: exact (identity) first, then phase 1
+            # strict (widening/subtyping, no boxing), then phase 2 loose
+            # (adds boxing/unboxing). A widening-applicable candidate thus
+            # always wins over a boxing-only sibling — javac's behavior —
+            # instead of both surviving one merged `compatible` tier.
+            exact = [c for c in pool if self._param_types_match(c, arg_types)]
+            if exact:
+                target, conf = _resolve_tier(exact)
+                if target is not None:
+                    return target, conf
+            strict = [
+                c for c in pool
+                if self._param_types_compatible(
+                    c, arg_types, arg_ctx, allow_boxing=False,
+                    allow_method_type_inference=allow_method_type_inference,
+                )
+            ]
+            if strict:
+                target, conf = _resolve_tier(strict)
+                if target is not None:
+                    return target, conf
+            loose = [
+                c for c in pool
+                if self._param_types_compatible(
+                    c, arg_types, arg_ctx,
+                    allow_method_type_inference=allow_method_type_inference,
+                )
+            ]
+            return _resolve_tier(loose)
+
+        non_vararg = [
+            c for c in by_arity if not self._is_phase3_only(c, arg_types, arg_ctx)
+        ]
+        phase3 = [
+            c for c in by_arity if self._is_phase3_only(c, arg_types, arg_ctx)
+        ]
+        target, conf = _rank(non_vararg)
+        if target is not None:
+            return target, conf
+        return _rank(phase3)