adl-toolkit 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,2947 @@
+"""Type and generic-resolution helpers for Java call resolution.
+
+This mixin is intentionally policy-free: it keeps the resolver facade's
+existing method contract while isolating generic text manipulation.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+import re
+from typing import Dict, List, Optional, Set, Tuple
+
+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 (
+    ASSERTJ_ASSERT_FACTORY_OWNERS,
+    JAVA_LANG_SIMPLE_TYPES,
+    JAVA_GENERIC_METHOD_STUB_RETURNS,
+    JAVA_GENERIC_TYPE_PARAM_STUBS,
+    JAVA_OBJECT_MEMBER_RETURNS,
+    JAVA_STATIC_FIELD_STUB_TYPES,
+    JAVA_STATIC_METHOD_STUB_RETURNS,
+    JAVA_THROWABLE_SIMPLE_TYPES,
+    JAVA_TIME_CONVERSION_RETURNS,
+    JAVA_TIME_SELF_RETURNING_EXACT,
+    JAVA_TIME_SELF_RETURNING_PREFIXES,
+    JAVA_TIME_TEMPORAL_TYPES,
+    SPRING_BEAN_CONTAINER_TYPES,
+    _FLOATING_POINT_LITERAL_TYPES,
+    _INTEGER_LITERAL_TYPES,
+    _LAMBDA_ARG_TYPE,
+    _LITERAL_ARG_TYPE,
+    _NULL_ARG_TYPE,
+    argument_nodes,
+)
+from adl_drift.lang.java.resolution.model import (
+    ImportContext as _ImportContext,
+    LocalScopes as _LocalScopes,
+)
+
+
+# JDK static factories whose result element type is exactly the (single,
+# statically known) argument type: `List.of(a, b)` is `List<A>`; the raw
+# result type is fixed whatever the elements are.
+# `List.of`/`Set.of`/`Stream.of` keep the simple raw name: the owner must be
+# imported at the call site for the call to compile, so the result spelling
+# resolves in the caller's own import context. `Arrays.asList`/`EnumSet.of`
+# are spelled fully qualified instead — a file calling `Arrays.asList(..)`
+# need not import `List` at all, and an unresolvable simple `List` argument
+# would be judged *incompatible* with an `Iterable` parameter (dropping the
+# candidate, a false negative) rather than unknown. `_external_type_name`
+# keeps a dotted spelling as written, so the JDK subtype facts still apply.
+_ELEMENT_PRESERVING_STATIC_FACTORIES = {
+    ("java.util.List", "of"): "List",
+    ("java.util.stream.Stream", "of"): "Stream",
+    ("java.util.Set", "of"): "Set",
+    ("java.util.Arrays", "asList"): "java.util.List",
+    ("java.util.EnumSet", "of"): "java.util.EnumSet",
+}
+_MATH_PROMOTING_STATICS = frozenset({
+    "abs", "absExact", "max", "min", "addExact", "subtractExact", "multiplyExact",
+    "negateExact", "incrementExact", "decrementExact",
+})
+_ENUMSET_FACTORIES = frozenset({"of", "allOf", "noneOf", "range", "copyOf", "complementOf"})
+
+_BOOLEAN_RESULT_BINARY_OPERATORS = frozenset({"==", "!=", "<", ">", "<=", ">=", "&&", "||"})
+_ARITHMETIC_BINARY_OPERATORS = frozenset({"+", "-", "*", "/", "%"})
+# JLS 5.1.8 unboxing, keyed by simple name (a `java.lang.`-qualified spelling
+# reduces to the same key); primitives map to themselves.
+_UNBOXED_PRIMITIVE = {
+    "byte": "byte", "short": "short", "char": "char", "int": "int",
+    "long": "long", "float": "float", "double": "double", "boolean": "boolean",
+    "Byte": "byte", "Short": "short", "Character": "char", "Integer": "int",
+    "Long": "long", "Float": "float", "Double": "double", "Boolean": "boolean",
+}
+
+
+def _unboxed_primitive(type_text: Optional[str]) -> Optional[str]:
+    if not type_text:
+        return None
+    return _UNBOXED_PRIMITIVE.get(erased_type(type_text).strip().rsplit(".", 1)[-1])
+
+
+def _unary_numeric_promotion(type_text: Optional[str]) -> Optional[str]:
+    """JLS 5.6.1: `byte`/`short`/`char` (and their boxes) promote to `int`;
+    `int`/`long`/`float`/`double` keep their type; anything else is unknown."""
+    unboxed = _unboxed_primitive(type_text)
+    if unboxed in ("byte", "short", "char", "int"):
+        return "int"
+    if unboxed in ("long", "float", "double"):
+        return unboxed
+    return None
+
+
+def _binary_numeric_promotion(left: Optional[str], right: Optional[str]) -> Optional[str]:
+    """JLS 5.6.2, only when both operands are statically known numerics."""
+    left_promoted = _unary_numeric_promotion(left)
+    right_promoted = _unary_numeric_promotion(right)
+    if left_promoted is None or right_promoted is None:
+        return None
+    for wider in ("double", "float", "long"):
+        if wider in (left_promoted, right_promoted):
+            return wider
+    return "int"
+
+
+_PRIMITIVE_TYPE_NAMES = frozenset({
+    "boolean", "byte", "char", "short", "int", "long", "float", "double",
+})
+
+
+_MEMO_MISS = object()
+
+
+class TypeResolutionMixin:
+    def _infer_arg_type(
+        self, node, source: bytes,
+        local_types: "_LocalScopes", param_types: Dict[str, str],
+        field_types: Dict[str, str], leaf=None,
+    ) -> Optional[str]:
+        """Best-effort static type of one call argument expression. Returns
+        None for anything not statically knowable from a declaration (method
+        calls, general `obj.field` access chains, binary/ternary expressions,
+        array creation, lambdas, ...) — the caller then treats the *whole*
+        arg-type list as unknown rather than guessing (P1.7's precision-first
+        spirit).
+
+        A handful of expression forms *do* have a statically-determined type
+        the way a plain literal or bare identifier does, and are unwrapped
+        here so a call site using one is type-checked against overloads the
+        same way its simpler equivalent is (B-01 fix — a `save(-1)`/`save((1))`/
+        `save(this.count)` argument used to fall through to None and, via
+        `_select_overload`'s unknown-arg branch, either resolve a sole
+        type-incompatible overload at full confidence or fan out to
+        incompatible siblings, asymmetric with the `save(1)`/`save(count)`
+        forms that resolved correctly):
+        - `parenthesized_expression` — `(e)` has the exact type of `e`.
+        - `unary_expression` — `!e` is `boolean`; `-e`/`+e`/`~e` take the
+          operand's numeric type, with JLS 5.6.1 unary numeric promotion
+          (`byte`/`short`/`char` -> `int`) applied so `-b` on a `byte`
+          resolves as `int`, never exact-matching a `save(byte)` overload it
+          cannot legally reach. Any operand whose type isn't a known numeric
+          stays None (never guessed).
+        - `field_access` limited to `this.<field>` — resolved from the
+          enclosing class's own+inherited `field_types` exactly as a bare
+          `<field>` identifier already is. A general `obj.field` needs
+          receiver resolution and stays None (unchanged).
+        - `leaf` (optional, batch 26) — a callback consulted for a
+          `method_invocation`/non-`this` `field_access` operand this
+          function itself never types; the argument-typing paths pass
+          `_arg_type_leaf` so composite expressions over calls are typed.
+        - `array_access` — `arr[i]` has the element type of `arr`'s own
+          statically-known type (recursing through this same function, so
+          `args[0]` off a `String[] args` parameter resolves to `String`,
+          and a nested `matrix[0][1]` peels one `[]` per access). Previously
+          fell through to None like any other unhandled expression, which
+          made `_infer_arg_types` give up on the *whole* call and fan out
+          across every same-arity overload at 0.55 confidence even when the
+          indexed array's element type made the call unambiguous (e.g.
+          `ApplicationModules.of(args[0])` fanning out to
+          `of(CacheKey)`/`of(Class)`/`of(String)` instead of resolving
+          `of(String)` alone)."""
+        if node.type in _INTEGER_LITERAL_TYPES:
+            text = self._text(node, source)
+            return "long" if text.endswith(("l", "L")) else "int"
+        if node.type in _FLOATING_POINT_LITERAL_TYPES:
+            text = self._text(node, source)
+            return "float" if text.endswith(("f", "F")) else "double"
+        if node.type in _LITERAL_ARG_TYPE:
+            return _LITERAL_ARG_TYPE[node.type]
+        if node.type == "null_literal":
+            return _NULL_ARG_TYPE
+        if node.type == "method_reference":
+            # A poly expression: compatible with a functional-interface
+            # parameter, never directly with Object or a primitive. Keep a
+            # sentinel until candidate-parameter compatibility is checked;
+            # guessing a concrete Function type here would incorrectly
+            # exclude Consumer/Predicate/etc. Unlike a lambda (below), an
+            # unbound/bound/static method reference carries no declared
+            # parameter list of its own to narrow by, so it stays the bare
+            # sentinel.
+            return _LAMBDA_ARG_TYPE
+        if node.type == "lambda_expression":
+            # Same poly-expression sentinel as a method reference, plus two
+            # syntactic, JLS-exact facts this lambda's own source already
+            # proves about itself — its declared parameter count, and (for a
+            # block body only) whether it contains a `return <expr>;` —
+            # encoded onto the sentinel so `_param_types_compatible` can
+            # exclude a same-arity sibling overload whose SAM arity/return
+            # kind this lambda provably cannot satisfy (E1,
+            # JAVA_METRICS_SPRING_MODULITH_PRECISION_SAMPLE.md:
+            # `Scenario.stimulate(Runnable/Supplier/Function/BiConsumer/
+            # BiFunction)` fanned out to all five regardless of the lambda's
+            # own arity). An expression body's void/value-compatibility is
+            # not attempted (JLS 15.27.2: a non-void statement-expression
+            # body is compatible with *both*) — only a block body's return
+            # statements are unambiguous, and only in the "found a value
+            # return" direction: a block with no `return <expr>;` might
+            # still never complete normally (an always-throwing/infinite-loop
+            # body is vacuously both void- and value-compatible per JLS), so
+            # "no value return found" never excludes a value-compatible
+            # sibling — only proven presence of one ever excludes anything.
+            return f"{_LAMBDA_ARG_TYPE}:{self._lambda_shape(node, source)}"
+        if node.type == "class_literal":
+            # `Float.class` has type Class<Float>; erasure is Class.  This is
+            # sufficient (and required) to prefer `withType(Class)` over the
+            # looser `withType(Object)` overload in phase 1.
+            return "Class"
+        if node.type in ("object_creation_expression", "cast_expression"):
+            type_node = node.child_by_field_name("type")
+            return self._text(type_node, source) if type_node is not None else None
+        if node.type == "array_creation_expression":
+            type_node = node.child_by_field_name("type")
+            if type_node is None:
+                return None
+            dimensions = sum(
+                1 for child in node.children
+                if child.type in ("dimensions", "dimensions_expr")
+            )
+            return self._text(type_node, source) + "[]" * max(1, dimensions)
+        if node.type == "parenthesized_expression":
+            inner = next((c for c in node.children if c.is_named), None)
+            if inner is None:
+                return None
+            return self._infer_arg_type(
+                inner, source, local_types, param_types, field_types, leaf=leaf)
+        if node.type == "unary_expression":
+            op_node = node.child_by_field_name("operator")
+            op = self._text(op_node, source) if op_node is not None else ""
+            if op == "!":
+                return "boolean"
+            operand = node.child_by_field_name("operand")
+            if op in ("-", "+", "~") and operand is not None:
+                inner = self._infer_arg_type(
+                    operand, source, local_types, param_types, field_types, leaf=leaf)
+                if inner in ("byte", "short", "char"):
+                    return "int"  # JLS 5.6.1 unary numeric promotion
+                if inner in ("int", "long", "float", "double"):
+                    return inner
+            return None
+        if node.type == "instanceof_expression":
+            # JLS 15.20.2: `boolean` whatever the operand or tested type.
+            return "boolean"
+        if node.type == "binary_expression":
+            operator = node.child_by_field_name("operator")
+            left = node.child_by_field_name("left")
+            right = node.child_by_field_name("right")
+            if operator is None or left is None or right is None:
+                return None
+            op = self._text(operator, source)
+            if op in _BOOLEAN_RESULT_BINARY_OPERATORS:
+                # JLS 15.20 (relational), 15.21 (equality), 15.23/15.24
+                # (conditional-and/or): the result is `boolean` regardless
+                # of the operand types, so nothing about the operands needs
+                # to be known. Batch 24: `assertTrue(quantity > 0)` /
+                # `assertTrue(a.isX() || b.isY())` used to stay unknown and
+                # fan out to the `BooleanSupplier` sibling at 0.55 whenever
+                # an operand was an unresolvable call.
+                return "boolean"
+            left_type = self._infer_arg_type(left, source, local_types, param_types, field_types, leaf=leaf)
+            right_type = self._infer_arg_type(right, source, local_types, param_types, field_types, leaf=leaf)
+            if op == "+" and "String" in (left_type, right_type):
+                # JLS 15.18.1: if either operand of `+` is String, the result
+                # is String regardless of the other operand's type.
+                return "String"
+            if op in _ARITHMETIC_BINARY_OPERATORS:
+                # JLS 5.6.2 binary numeric promotion, applied only when both
+                # operand types are statically known (primitive or boxed):
+                # `n % 2` off an `int n` is `int`, `1L + n` is `long`.
+                # Anything else (an unknown operand, a non-numeric reference)
+                # stays None — never guessed.
+                return _binary_numeric_promotion(left_type, right_type)
+            if op in ("&", "|", "^"):
+                if _unboxed_primitive(left_type) == "boolean" and _unboxed_primitive(right_type) == "boolean":
+                    return "boolean"  # JLS 15.22.2
+                promoted = _binary_numeric_promotion(left_type, right_type)
+                return promoted if promoted in ("int", "long") else None  # JLS 15.22.1
+            if op in ("<<", ">>", ">>>"):
+                # JLS 15.19: unary numeric promotion of the left operand only.
+                promoted = _unary_numeric_promotion(left_type)
+                return promoted if promoted in ("int", "long") else None
+            return None
+        if node.type == "field_access":
+            obj = node.child_by_field_name("object")
+            field_node = node.child_by_field_name("field")
+            if obj is not None and obj.type == "this" and field_node is not None:
+                fname = self._text(field_node, source)
+                if fname in field_types:
+                    return field_types[fname]
+            if obj is not None and field_node is not None and self._text(field_node, source) == "length":
+                # JLS 10.7: `array.length` is `int` for every array; only
+                # applied when the receiver's own type is statically known
+                # to be an array (a declared local/parameter/field), so a
+                # `length` field on an unknown reference type is untouched.
+                obj_type = self._infer_arg_type(obj, source, local_types, param_types, field_types, leaf=leaf)
+                if obj_type is not None and erased_type(obj_type).strip().endswith("[]"):
+                    return "int"
+            return leaf(node) if leaf is not None else None
+        if node.type == "array_access":
+            array_node = node.child_by_field_name("array")
+            if array_node is None:
+                return None
+            array_type = self._infer_arg_type(
+                array_node, source, local_types, param_types, field_types, leaf=leaf)
+            if array_type is None:
+                return None
+            erased_array = erased_type(array_type).strip()
+            if not erased_array.endswith("[]"):
+                return None
+            element_type = erased_array[:-2].strip()
+            return element_type or None
+        if node.type == "ternary_expression":
+            # JLS 15.25: a conditional whose branches are both statically
+            # typed is itself typed only in the two exact cases modeled here:
+            # identical branch types (`c ? "a" : "b"` is `String`) and a
+            # `null` literal against a *reference* branch (`c ? FORMAT :
+            # null` is the reference type -- `null` -> reference is a
+            # widening reference conversion, so nothing is guessed). A
+            # primitive against `null` would box, and differing reference or
+            # numeric branches need a least-upper-bound/binary-numeric
+            # promotion; those stay None so overload selection keeps its
+            # unknown-argument contract instead of fabricating an exact
+            # match. Regression: `setShowDeprecated(flag ? FORMAT : null)`
+            # used to fan out to the `(boolean)` sibling as well.
+            consequence = node.child_by_field_name("consequence")
+            alternative = node.child_by_field_name("alternative")
+            if consequence is None or alternative is None:
+                return None
+            branch_types = [
+                self._infer_arg_type(
+                    branch, source, local_types, param_types, field_types, leaf=leaf)
+                for branch in (consequence, alternative)
+            ]
+            if any(
+                t is None or t.startswith(_LAMBDA_ARG_TYPE) for t in branch_types
+            ):
+                return None
+            if branch_types[0] == branch_types[1]:
+                return branch_types[0]
+            non_null = [t for t in branch_types if t != _NULL_ARG_TYPE]
+            if len(non_null) == 1 and erased_type(non_null[0]) not in _PRIMITIVE_TYPE_NAMES:
+                return non_null[0]
+            return None
+        if node.type == "identifier":
+            name = self._text(node, source)
+            local = local_types.type_at(name, node.start_byte)
+            if local is not None:
+                return local
+            if local_types.declared_at(name, node.start_byte):
+                # Shadowed by a local/lambda-parameter whose own type
+                # couldn't be resolved — the outer param/field of the same
+                # name is not what this identifier refers to here.
+                return None
+            if name in param_types:
+                return param_types[name]
+            if name in field_types:
+                return field_types[name]
+            return leaf(node) if leaf is not None else None
+        if node.type == "method_invocation" and leaf is not None:
+            # Batch 26: `leaf` (see `_arg_type_leaf`) types a call/field
+            # operand with the same declared source/JDK return facts the
+            # narrowing and exact-ranking argument paths already trust, so
+            # a *composite* argument built from one -- `resource.usages()
+            # - 3`, `a.size() + b.size()`, `(cond ? x.count() : 0)` --
+            # is typed by the JLS rules above instead of collapsing to
+            # unknown at the first call operand. Plain `_infer_arg_type`
+            # callers pass no leaf and keep the declaration-only contract.
+            return leaf(node)
+        return None
+
+    @staticmethod
+    def _lambda_shape(node, source: bytes) -> str:
+        """`"{param_count}:{shape}"` for a `lambda_expression` node, where
+        `shape` is `"value"` when a block body provably contains a value
+        `return`, else `"any"` (see `_infer_arg_type`'s lambda branch for
+        the safety argument behind never producing `"void"` here)."""
+        params_node = node.child_by_field_name("parameters")
+        if params_node is None:
+            count = 0
+        elif params_node.type == "identifier":
+            count = 1
+        else:
+            count = sum(1 for c in params_node.children if c.is_named)
+        body = node.child_by_field_name("body")
+        shape = "any"
+        if body is not None and body.type == "block":
+            stack = [body]
+            while stack:
+                child = stack.pop()
+                if child is not body and child.type in (
+                    "lambda_expression", "method_declaration",
+                    "constructor_declaration", "class_declaration",
+                    "interface_declaration", "enum_declaration",
+                    "anonymous_class_body",
+                ):
+                    continue
+                if child.type == "return_statement" and any(
+                    c.is_named for c in child.children
+                ):
+                    shape = "value"
+                    break
+                stack.extend(child.children)
+        return f"{count}:{shape}"
+
+    def _infer_arg_types(
+        self, args_node, source: bytes,
+        local_types: "_LocalScopes", param_types: Dict[str, str],
+        field_types: Dict[str, str],
+    ) -> Optional[List[str]]:
+        """`[erased_type, ...]` for every argument iff *all* are statically
+        knowable; None (unknown) the moment any single argument isn't —
+        overload selection then falls back to the reduced-confidence
+        candidate set rather than guessing which unknown-typed arg matches
+        which parameter."""
+        arg_nodes = argument_nodes(args_node)
+        types: List[str] = []
+        for n in arg_nodes:
+            t = self._infer_arg_type(n, source, local_types, param_types, field_types)
+            if t is None:
+                return None
+            types.append(erased_type(t))
+        return types
+
+    def _infer_known_arg_type_for_narrowing(
+        self, node, source: bytes, arg_ctx: "_ImportContext",
+        local_types: "_LocalScopes", param_types: Dict[str, str],
+        field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Best-effort argument type used *only* to narrow an otherwise-total
+        overload fan-out (see `_narrow_candidates_by_known_arg_types`).
+
+        `_infer_arg_type`'s declaration-only contract deliberately excludes
+        method calls and cross-class field access (P1.7): guessing a wrong
+        *value* type there could pick a single wrong overload at full
+        confidence. Narrowing carries no such risk — a wrongly inferred type
+        here can only ever *exclude* a same-arity sibling a resolved type
+        provably cannot reach; it can never fabricate an edge or select a
+        winner (`_narrow_candidates_by_known_arg_types` falls back to the
+        full candidate set whenever narrowing would discard everything).
+        That asymmetry is why this reuses the same source/JDK return-type
+        propagation the `var`/fluent-chain typing already trusts
+        (`_generic_method_invocation_return_type`,
+        `_source_static_field_arg_type`) instead of staying as conservative
+        as `_infer_arg_type`. Batch 26: the same facts are now applied
+        through `_arg_type_leaf`, so they also reach a call/field operand
+        nested inside a binary/unary/ternary/parenthesized argument."""
+        leaf = self._arg_type_leaf(
+            source, arg_ctx.module, arg_ctx.enclosing_class_id, arg_ctx.import_map,
+            arg_ctx.wildcard_packages, local_types, param_types, field_types, {},
+        )
+        return self._infer_arg_type(
+            node, source, local_types, param_types, field_types, leaf=leaf,
+        )
+
+    def _arg_type_leaf(
+        self, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ):
+        """Callback for `_infer_arg_type(leaf=...)`: the declared source/JDK
+        type of one call or field-access *operand* (batch 26).
+
+        - `method_invocation`: a uniquely selected source method's declared
+          return (`_generic_method_invocation_return_type`, incl. the JDK
+          fixed-return facts a typed receiver reaches) or an exact external
+          static fact (`_external_static_call_return_type`). A source return
+          canonicalized to its FQN is re-spelled the way the call site
+          spells it when both resolve to the same class, so an exact
+          overload match is not hidden by spelling.
+        - `field_access`: a source static field (`Type.FIELD`, incl. enum
+          constants), an exact JDK constant, a source instance field off a
+          typed local/parameter/field, or — new — any field off a receiver
+          expression `_declared_receiver_type_text` can type (nested
+          `Handler.callCounter.beforeEachCalls`, `tasks.get(k).threadName`,
+          `((T) x).field`), see `_field_access_declared_type`.
+        - `identifier`: an explicitly static-imported field/enum constant.
+
+        Every fact here is a declaration (a field's declared type, a
+        method's declared return, a JDK contract), never a value guess; an
+        unknown operand still yields None so the enclosing expression
+        stays untyped."""
+        def leaf(node) -> Optional[str]:
+            if node.type == "method_invocation":
+                source_return = self._generic_method_invocation_return_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, field_types, param_types,
+                    type_param_bounds,
+                )
+                if source_return is not None:
+                    return self._call_site_spelling(
+                        source_return, module_name, enclosing_class_id,
+                        import_map, wildcard_packages,
+                    )
+                return self._external_static_call_return_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types,
+                )
+            if node.type == "field_access":
+                field_type = self._source_static_field_arg_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types,
+                ) or self._external_static_field_arg_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types,
+                ) or self._source_instance_field_arg_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types,
+                ) or self._field_access_declared_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types,
+                    type_param_bounds,
+                )
+                if field_type is None:
+                    return None
+                # A field's declared type is spelled in its *declaring* file
+                # (`Namespace GLOBAL` inside `ExtensionContext`); the helpers
+                # canonicalize a source type to its exact class id, and the
+                # call-site spelling is restored here only when it names the
+                # same class, so a caller that never imports the nested
+                # `Namespace` still matches `get(ExtensionContext.Namespace)`.
+                return self._call_site_spelling(
+                    field_type, module_name, enclosing_class_id, import_map,
+                    wildcard_packages,
+                )
+            if node.type == "identifier":
+                return self._static_imported_field_arg_type(
+                    node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types,
+                )
+            return None
+        return leaf
+
+    def _call_site_spelling(
+        self, type_text: str, module_name: str, enclosing_class_id: Optional[str],
+        import_map: Dict[str, str], wildcard_packages: List[str],
+    ) -> str:
+        """Source-return propagation canonicalizes a return type to its FQN
+        for receiver chains. For an overload argument that can hide an
+        exact match, restore the call-site simple spelling only when both
+        forms resolve to the same class (or, for a JDK owner canonicalized
+        by the declaring file, when the caller imports that very class)."""
+        erased_arg = erased_type(type_text)
+        if "." not in erased_arg:
+            return erased_arg
+        simple_arg = erased_arg.rsplit(".", 1)[-1]
+        qualified_id = self._resolve_declared_type(
+            erased_arg, module_name, import_map, wildcard_packages, enclosing_class_id,
+        )
+        simple_id = self._resolve_declared_type(
+            simple_arg, module_name, import_map, wildcard_packages, enclosing_class_id,
+        )
+        if qualified_id is not None and qualified_id == simple_id:
+            return simple_arg
+        if (
+            qualified_id is None and simple_id is None
+            and erased_arg.startswith("java.")
+            and (
+                import_map.get(simple_arg) == erased_arg
+                or erased_arg.rsplit(".", 1)[0] in wildcard_packages
+            )
+        ):
+            return simple_arg
+        return erased_arg
+
+    def _field_access_declared_type(
+        self, field_access, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> Optional[str]:
+        """Declared type of `<expr>.field` for any receiver expression
+        `_declared_receiver_type_text` can type (batch 26): a nested field
+        chain (`Handler.callCounter.beforeEachCalls`), a call result
+        (`tasks.get("a").threadName`), a cast (`((Info) o).count`).
+        JLS 15.11.1: the type of a field access is the field's declared
+        type in the receiver's *static* type — exact, never a value guess.
+        A field declared as a bare class type variable (`T value` on
+        `Box<T>`) is substituted from the receiver's own type arguments
+        when they are spelled at the site (`Box<String> b; b.value`) and
+        left unknown otherwise, so an unbound `T` can never reach overload
+        ranking as if it were a class name."""
+        obj = field_access.child_by_field_name("object")
+        field_node = field_access.child_by_field_name("field")
+        if obj is None or field_node is None or field_node.type != "identifier":
+            return None
+        if obj.type == "this":
+            return None  # `this.field` is handled by `_infer_arg_type` itself.
+        obj_type = self._declared_receiver_type_text(
+            obj, source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, field_types, param_types,
+            type_param_bounds,
+        )
+        if obj_type is None:
+            return None
+        field_name = self._text(field_node, source)
+        erased_obj = erased_type(obj_type).strip()
+        if erased_obj.endswith("[]"):
+            return "int" if field_name == "length" else None  # JLS 10.7
+        owner_id = self._resolve_declared_type(
+            erased_obj, module_name, import_map, wildcard_packages, enclosing_class_id,
+        )
+        if owner_id is None:
+            return None
+        declared = self._all_field_types(owner_id).get(field_name)
+        if declared is None:
+            return None
+        bound = self._bind_class_type_variable(owner_id, obj_type, declared)
+        return self._canonical_declared_type(owner_id, bound) if bound is not None else None
+
+    def _infer_contextual_arg_types(
+        self, args_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> Optional[List[str]]:
+        """Argument types for the narrow root-new overload path.
+
+        Extends ordinary literal/declaration inference only with a nested
+        source call's declared return type, an exact JDK static/constant
+        fact, and (batch 26, via `_arg_type_leaf`) the declared type of a
+        field reached through any typable receiver expression — each a
+        declaration, never a value guess — including when such a call or
+        field is an *operand* of a binary/unary/ternary argument. Any other
+        unknown keeps the whole overload unresolved, preventing the
+        reduced-confidence fan-out used by general call resolution.
+        """
+        leaf = self._arg_type_leaf(
+            source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, param_types, field_types,
+            type_param_bounds,
+        )
+        inferred: List[str] = []
+        for arg in argument_nodes(args_node):
+            arg_type = self._infer_arg_type(
+                arg, source, local_types, param_types, field_types, leaf=leaf,
+            )
+            if arg_type is None:
+                return None
+            inferred.append(erased_type(arg_type))
+        return inferred
+
+    def _nearest_common_source_supertype(
+        self, type_texts: List[str], module_name: str, import_map: Dict[str, str],
+        wildcard_packages: List[str], enclosing_class_id: Optional[str],
+    ) -> Optional[str]:
+        """Simple name of the single nearest source supertype shared by every
+        type in `type_texts`, or None.
+
+        Each text must resolve to a source class through the caller's import
+        context. The candidate set is the intersection of every class's own
+        id plus its INHERITS/IMPLEMENTS ancestors; a candidate survives only
+        when no other candidate is its descendant. Exactly one survivor is
+        returned, so `enum A implements I` and `enum B implements I` yield
+        `I`, while types sharing two unrelated interfaces stay unresolved.
+        """
+        if len(type_texts) < 2:
+            return None
+        lineages: List[Set[str]] = []
+        for text in type_texts:
+            class_id = self._resolve_declared_type(
+                text, module_name, import_map, wildcard_packages, enclosing_class_id,
+            )
+            if class_id is None or class_id not in self.builder._nodes:
+                return None
+            lineages.append({class_id, *self._class_ancestors(class_id)})
+        common = set.intersection(*lineages)
+        nearest = [
+            candidate for candidate in common
+            if not any(
+                candidate in self._class_ancestors(other)
+                for other in common if other != candidate
+            )
+        ]
+        if len(nearest) != 1:
+            return None
+        node = self.builder._nodes.get(nearest[0])
+        return node.name if node is not None else None
+
+    def _source_static_field_arg_type(
+        self, field_access, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Declared type of a source static-field argument (`Type.FIELD`).
+
+        This is intentionally contextual-overload-only. The qualifier must
+        be an unshadowed identifier that resolves strictly through the current
+        package/import context.
+        """
+        owner_node = field_access.child_by_field_name("object")
+        field_node = field_access.child_by_field_name("field")
+        if owner_node is None or owner_node.type != "identifier" or field_node is None:
+            return None
+        owner_name = self._text(owner_node, source)
+        if (
+            local_types.type_at(owner_name, owner_node.start_byte) is not None
+            or owner_name in param_types
+            or owner_name in field_types
+        ):
+            return None
+        owner_id = self._resolve_declared_type(
+            owner_name, module_name, import_map, wildcard_packages,
+            enclosing_class_id,
+        )
+        if owner_id is None:
+            return None
+        field_name = self._text(field_node, source)
+        declared_field = self._all_field_types(owner_id).get(field_name)
+        if declared_field is not None:
+            return self._canonical_declared_type(owner_id, declared_field)
+        owner = self.builder._nodes.get(owner_id)
+        if (
+            owner is not None
+            and owner.metadata.get("java_type_kind") == "enum"
+            and field_name in owner.metadata.get("enum_constants", ())
+        ):
+            # Every declared enum constant has exactly its enum type.  Keep
+            # this exact and metadata-backed: an arbitrary unknown static
+            # field on an enum is not assumed to be an enum constant.
+            return self._text(owner_node, source)
+        return None
+
+    def _source_instance_field_arg_type(
+        self, field_access, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Declared type of `receiver.field` where `receiver` is a local/
+        parameter/field whose own declared type is a resolvable source
+        class — e.g. `other.classes` where `other` is a `Classes` parameter
+        and `Classes` declares `private final List<JavaClass> classes`
+        (E4: `Classes.and(Classes classes) { return and(classes.classes);
+        }` fanned out between `and(Classes)`/`and(Collection)` because
+        `classes.classes`'s field access, unlike `this.field`, fell through
+        `_infer_arg_type` to unknown).
+
+        Narrowing-only (see `_infer_known_arg_type_for_narrowing`'s
+        docstring): a wrong guess here can only ever exclude a same-arity
+        sibling a resolved field type provably cannot reach, never select a
+        winner on its own. Mirrors `_source_static_field_arg_type`'s
+        `Type.FIELD` lookup, but keyed off the receiver's own declared
+        instance type instead of a type name qualifier — so it does not
+        also need that helper's "unshadowed identifier" guard (a static
+        qualifier must not be a local; this one's qualifier must be)."""
+        owner_node = field_access.child_by_field_name("object")
+        field_node = field_access.child_by_field_name("field")
+        if owner_node is None or owner_node.type != "identifier" or field_node is None:
+            return None
+        owner_name = self._text(owner_node, source)
+        owner_type = (
+            local_types.type_at(owner_name, owner_node.start_byte)
+            or param_types.get(owner_name)
+            or field_types.get(owner_name)
+        )
+        if owner_type is None:
+            return None
+        owner_id = self._resolve_declared_type(
+            owner_type, module_name, import_map, wildcard_packages,
+            enclosing_class_id,
+        )
+        if owner_id is None:
+            return None
+        field_name = self._text(field_node, source)
+        declared = self._all_field_types(owner_id).get(field_name)
+        if declared is None:
+            return None
+        bound = self._bind_class_type_variable(owner_id, owner_type, declared)
+        return self._canonical_declared_type(owner_id, bound) if bound is not None else None
+
+    def _canonical_declared_type(self, owner_id: str, declared: str) -> str:
+        """Re-spell a member type declared inside `owner_id`'s file as the
+        exact dotted class id when it names a source class there (resolved
+        in the *declaring* file's import context, incl. sibling nested
+        types in scope without an import), keeping any type arguments as
+        written. Primitives, arrays and external/unresolvable names are
+        returned unchanged. The consumer restores the call-site simple
+        spelling via `_call_site_spelling` when it names the same class."""
+        erased = erased_type(declared).strip()
+        if not erased or erased.endswith("[]") or erased in _PRIMITIVE_TYPE_NAMES:
+            return declared
+        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_ctx is None:
+            return declared
+        class_id = self._resolve_declared_type(
+            erased, owner_ctx.module, owner_ctx.import_map, owner_ctx.wildcard_packages,
+            owner_id,
+        )
+        if class_id is None or ":" not in class_id:
+            return declared
+        owner_module, qualname = class_id.rsplit(":", 1)
+        dotted = f"{self.builder._display_module(owner_module)}.{qualname}"
+        return dotted + (declared[declared.index("<"):] if "<" in declared else "")
+
+    def _bind_class_type_variable(
+        self, owner_id: str, receiver_type: str, declared: str,
+    ) -> Optional[str]:
+        """A member declared as a bare class type variable (`T value` on
+        `Box<T>`) has, at a use site, the receiver's corresponding type
+        argument (`Box<String> b; b.value` is `String`, JLS 4.5.2) — or no
+        knowable type at all off a raw/unparameterized receiver. Returning
+        the bare `T` would let overload ranking treat it as a class name
+        that is compatible with `Object` and nothing else, silently
+        selecting an `(Object, ..)` sibling at full confidence (batch 26
+        guard, applied to every field-typing path)."""
+        erased_field = erased_type(declared).strip()
+        owner_params = self._class_type_params.get(owner_id, [])
+        if erased_field not in owner_params:
+            return declared
+        receiver_args = self._generic_type_arguments(receiver_type)
+        if len(receiver_args) != len(owner_params):
+            return None
+        bound = receiver_args[owner_params.index(erased_field)]
+        if bound.strip().startswith("?"):
+            return self._wildcard_upper_bound(bound)
+        return bound
+
+    def _static_imported_field_arg_type(
+        self, node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Declared type of a bare identifier that is an explicit static
+        field import (`import static a.b.C.FIELD;`), e.g. `assertFalse
+        (tag2WasExecuted)` where `tag2WasExecuted` is `import static
+        ...TaggedTestCase.tag2WasExecuted`.
+
+        Mirrors `_source_static_field_arg_type`'s qualified-field lookup,
+        but for the unqualified spelling a static import allows -- the
+        qualifier check that helper does for `Type.FIELD` is done here by
+        requiring the name be absent from every local/param/own-field
+        scope first, then present in `import_map` (an explicit static
+        import; a wildcard `import static ...*;` is not indexed there and
+        stays unresolved, matching every other exact-import-only path in
+        this file)."""
+        if node.type != "identifier":
+            return None
+        name = self._text(node, source)
+        if (
+            local_types.type_at(name, node.start_byte) is not None
+            or local_types.declared_at(name, node.start_byte)
+            or name in param_types
+            or name in field_types
+            or name not in import_map
+        ):
+            return None
+        resolved = import_map[name]
+        owner_path, _, field_name = resolved.rpartition(".")
+        if not owner_path:
+            return None
+        owner_id = self._resolve_static_import_class(owner_path, module_name)
+        if owner_id is None:
+            return None
+        declared_field = self._all_field_types(owner_id).get(field_name)
+        if declared_field is not None:
+            return declared_field
+        if self._is_enum_constant(owner_id, field_name) and ":" in owner_id:
+            # A static-imported enum constant (`import static
+            # ...Mode.INCLUDE;`) has exactly its enum type. The enum's
+            # simple name need not be imported as a *type* at this call
+            # site, so the type is spelled as the exact dotted class id
+            # `_resolve_declared_type` accepts, the same way a static-
+            # imported source factory's owner is spelled for its fluent
+            # continuation (batch 25).
+            owner_module, owner_qualname = owner_id.rsplit(":", 1)
+            return f"{self.builder._display_module(owner_module)}.{owner_qualname}"
+        return None
+
+    def _is_enum_constant(self, class_id: str, name: str) -> bool:
+        """True iff `name` is a declared constant of the source enum
+        `class_id` (extractor-recorded metadata; never a guess about an
+        arbitrary static field on an enum)."""
+        owner = self.builder._nodes.get(class_id)
+        return (
+            owner is not None
+            and owner.metadata.get("java_type_kind") == "enum"
+            and name in owner.metadata.get("enum_constants", ())
+        )
+
+    def _external_static_field_arg_type(
+        self, field_access, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Declared type of an *external* (JDK) constant argument such as
+        `Integer.MAX_VALUE` or `Level.WARNING`, from the exact
+        `JAVA_STATIC_FIELD_STUB_TYPES` table (batch 24).
+
+        Narrowing-only, and as strict as `_external_static_call_return_type`:
+        the qualifier must be an unshadowed identifier that is *not* a
+        resolvable source type (a project class named `Level` always wins),
+        and must reach a fully-qualified owner through an explicit import or
+        the implicit `java.lang` package. `assertEquals(Integer.MAX_VALUE,
+        parse(...))` and `listener.stream(Level.WARNING)` (JUnit5's
+        `stream(Level)`/`stream(Class)` pair) stayed unknown before."""
+        owner_node = field_access.child_by_field_name("object")
+        field_node = field_access.child_by_field_name("field")
+        if owner_node is None or owner_node.type != "identifier" or field_node is None:
+            return None
+        owner_name = self._text(owner_node, source)
+        if (
+            local_types.type_at(owner_name, owner_node.start_byte) is not None
+            or local_types.declared_at(owner_name, owner_node.start_byte)
+            or owner_name in param_types
+            or owner_name in field_types
+        ):
+            return None
+        if self._resolve_declared_type(
+            owner_name, module_name, import_map, wildcard_packages,
+            enclosing_class_id,
+        ) is not None:
+            return None
+        external_fqn = import_map.get(owner_name)
+        if external_fqn is None and owner_name in JAVA_LANG_SIMPLE_TYPES:
+            external_fqn = f"java.lang.{owner_name}"
+        if external_fqn is None:
+            return None
+        return JAVA_STATIC_FIELD_STUB_TYPES.get(
+            (external_fqn, self._text(field_node, source)),
+        )
+
+    def _external_static_call_return_type(
+        self, call_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Return type for a small exact set of external static methods."""
+        receiver = call_node.child_by_field_name("object")
+        name_node = call_node.child_by_field_name("name")
+        if receiver is None or receiver.type != "identifier" or name_node is None:
+            return None
+        receiver_name = self._text(receiver, source)
+        if (
+            local_types.type_at(receiver_name, receiver.start_byte) is not None
+            or receiver_name in param_types
+            or receiver_name in field_types
+        ):
+            return None
+        if self._resolve_declared_type(
+            receiver_name, module_name, import_map, wildcard_packages,
+            enclosing_class_id,
+        ) is not None:
+            return None
+        external_fqn = import_map.get(receiver_name)
+        if external_fqn is None and receiver_name == "Arrays" and "java.util" in wildcard_packages:
+            external_fqn = "java.util.Arrays"
+        if external_fqn is None and receiver_name in JAVA_LANG_SIMPLE_TYPES:
+            # `java.lang` needs no import: `String.valueOf`, `Integer.parseInt`.
+            external_fqn = f"java.lang.{receiver_name}"
+        method_name = self._text(name_node, source)
+        fixed_return = JAVA_STATIC_METHOD_STUB_RETURNS.get((external_fqn or "", method_name))
+        if fixed_return is not None:
+            return fixed_return
+        if external_fqn == "java.lang.Math" and method_name in _MATH_PROMOTING_STATICS:
+            # `Math.abs/max/min/addExact/..` are overloaded per primitive
+            # and return exactly the promoted operand type (JLS 5.6.1/5.6.2
+            # over the declared overload set: `addExact(int,int) -> int`,
+            # `max(int,long) -> long`). Only fully known primitive/boxed
+            # operands are promoted; anything else stays unknown.
+            inferred = self._infer_contextual_arg_types(
+                call_node.child_by_field_name("arguments"), source, module_name,
+                enclosing_class_id, import_map, wildcard_packages, local_types,
+                param_types, field_types, {},
+            )
+            if inferred and all(_unboxed_primitive(t) in ("int", "long", "float", "double", "short", "byte", "char") for t in inferred):
+                if len(inferred) == 1:
+                    return _unary_numeric_promotion(inferred[0])
+                if len(inferred) == 2:
+                    return _binary_numeric_promotion(inferred[0], inferred[1])
+            return None
+        # `Arrays.stream(T[])` preserves the array component as the Stream
+        # element.  Keep the rule to one exact, reference-array shape: the
+        # primitive overloads (`int[]`, etc.) return specialized streams and
+        # need different lambda parameter types.
+        if external_fqn == "java.util.Arrays" and method_name == "stream":
+            args = call_node.child_by_field_name("arguments")
+            inferred = self._infer_arg_types(
+                args, source, local_types, param_types, field_types,
+            )
+            if inferred is None:
+                # The array is frequently the result of a nested call
+                # (`Arrays.stream(method.getGenericParameterTypes())`,
+                # `Arrays.stream(holder.items())`).  Reuse the same declared
+                # source/exact-JDK return facts that type a fluent receiver;
+                # anything still unknown keeps the Stream element unknown.
+                inferred = self._infer_contextual_arg_types(
+                    args, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types, {},
+                )
+            if inferred is not None and len(inferred) == 1:
+                component = inferred[0]
+                if component.endswith("..."):
+                    component = component[:-3] + "[]"
+                if component.endswith("[]") and component[:-2] not in {
+                    "boolean", "byte", "char", "short", "int", "long", "float", "double",
+                }:
+                    return f"Stream<{component[:-2]}>"
+        # `Optional.ofNullable(T)` retains the exact static type of its sole
+        # argument. This is needed before an immediately chained `map` can
+        # target-type its lambda parameter, including when that parameter and
+        # a captured local jointly select a source constructor overload.
+        # `null` has no concrete T, so it intentionally remains unknown.
+        if external_fqn == "java.util.Optional" and method_name == "ofNullable":
+            inferred = self._infer_arg_types(
+                call_node.child_by_field_name("arguments"), source,
+                local_types, param_types, field_types,
+            )
+            if inferred is not None and len(inferred) == 1 and inferred[0] != "null":
+                return f"Optional<{inferred[0]}>"
+        # `List.of(a, b, ...)` is a generic static factory.  Preserve its
+        # element type only when every argument has the same statically known
+        # type; computing a Java least-upper-bound here would be speculative.
+        # This exact case lets a following `stream().map(x -> x.sourceCall())`
+        # target the lambda parameter without emitting an external call edge.
+        # Batch 25 widens the same exact rule to the other element-preserving
+        # JDK factories that appear as overload arguments' receivers:
+        # `Arrays.asList(a, b).contains(x)`, `Set.of(...)`, `EnumSet.of(...)`.
+        factory_raw = _ELEMENT_PRESERVING_STATIC_FACTORIES.get((external_fqn or "", method_name))
+        if factory_raw is not None:
+            args = call_node.child_by_field_name("arguments")
+            inferred = self._infer_arg_types(
+                args, source, local_types, param_types, field_types,
+            )
+            if inferred is None:
+                inferred = self._infer_contextual_arg_types(
+                    args, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, param_types, field_types, {},
+                )
+            if inferred and len(inferred) == 1 and inferred[0].endswith("[]"):
+                inferred = [inferred[0][:-2]]
+            raw = factory_raw
+            if inferred and len(set(inferred)) == 1:
+                return f"{raw}<{inferred[0]}>"
+            if inferred and len(set(inferred)) > 1:
+                # Distinct source element types (`Stream.of(A.INSTANCE,
+                # B.INSTANCE)`) share a Java least upper bound. Accept it
+                # only when every argument resolves to a source class and
+                # exactly one nearest common source supertype exists; a JDK
+                # or multiply-bounded lub stays unknown.
+                common = self._nearest_common_source_supertype(
+                    sorted(set(inferred)), module_name, import_map,
+                    wildcard_packages, enclosing_class_id,
+                )
+                if common is not None:
+                    return f"{raw}<{common}>"
+        if external_fqn == "java.util.EnumSet" and method_name in _ENUMSET_FACTORIES:
+            # Every `EnumSet` factory returns an `EnumSet` whatever its
+            # element type; the JDK enum constants it is usually built from
+            # (`EnumSet.of(ChronoUnit.DAYS)`) have no source declaration to
+            # type the element by. The raw type is exact and is enough for
+            # the fixed-return members consulted next (`contains`/`isEmpty`/
+            # `size`); no element-typed (`E`-returning) `EnumSet` stub
+            # exists, so a raw receiver can never leak an unbound `E`.
+            return "java.util.EnumSet"
+        return None
+
+    def _contextual_overload_arg_types(
+        self, candidates: List[str], arg_count: int, arg_types: Optional[List[str]],
+        args_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> Optional[List[str]]:
+        """Refine unknown args only when overload fan-out is otherwise possible."""
+        if arg_types is not None:
+            return arg_types
+        if sum(self._arity_matches(candidate, arg_count) for candidate in candidates) <= 1:
+            return arg_types
+        refined = self._infer_contextual_arg_types(
+            args_node, source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, param_types, field_types,
+            type_param_bounds,
+        )
+        if refined is None:
+            return arg_types
+        applicable, _ = self._select_overload(
+            candidates, arg_count, refined, lambda _candidate: 0.9,
+            _ImportContext(
+                module_name, import_map, wildcard_packages, enclosing_class_id,
+            ),
+            allow_method_type_inference=True,
+        )
+        # Preserve the established unknown-argument fan-out contract when
+        # contextual inference proves no overload applicable.
+        return refined if applicable is not None else arg_types
+
+    def _resolve_declared_type(
+        self, type_text: str, module_name: str, import_map: Dict[str, str],
+        wildcard_packages: List[str], enclosing_class_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """Declared-type text (`Foo`, `List<User>`, `Box<T>`, `Foo[]`, a
+        Lombok/erasure-normalized varargs `Foo...`) -> CLASS node id.
+
+        Uses `erased_type()` to strip generics/arrays down to the *raw*
+        type — correct for receiver dispatch (`Box<T> b; b.get()` must look
+        up `get` on raw `Box`, not `T`; contrast with
+        `CallGraphBuilder._resolve_annotation`, which Java's TYPE_OF/RETURNS
+        edges use and which deliberately keeps the *inner* generic argument
+        instead, mirroring Python's `List[X]` -> `X` semantics for "what
+        this annotation carries" — the two helpers answer different
+        questions on purpose, see `_resolve_annotation`'s docstring).
+
+        Name resolution itself reuses `CallGraphBuilder._resolve_name` in
+        strict mode: same-package (same-module) -> explicit import -> (a
+        miss falls through to `wildcard_packages`, tried in import order,
+        each via `CallGraphBuilder._lookup_qualified("<pkg>.<t>", ...)` —
+        `import lib.*;` then `Service s;` looks up `lib.Service`) ->
+        unresolved for `java.lang`/external JDK types, which is correct:
+        only in-repo source can be resolved from source. `strict=True`
+        deliberately skips `_resolve_name`'s own non-strict unique-simple-
+        name fallback (over-approximation across every class in the repo,
+        not scoped to an actually-imported package) — `wildcard_packages`
+        is the precise replacement for that approximation, per the P4.4 Fix
+        Applied notes.
+        """
+        memo = self._declared_type_memo
+        key = None
+        if memo is not None and id(import_map) in self._file_import_map_ids:
+            key = (
+                type_text, module_name, id(import_map),
+                tuple(wildcard_packages), enclosing_class_id,
+            )
+            hit = memo.get(key, _MEMO_MISS)
+            if hit is not _MEMO_MISS:
+                return hit
+        result = self._resolve_declared_type_uncached(
+            type_text, module_name, import_map, wildcard_packages, enclosing_class_id,
+        )
+        if key is not None:
+            memo[key] = result
+        return result
+
+    def _resolve_declared_type_uncached(
+        self, type_text: str, module_name: str, import_map: Dict[str, str],
+        wildcard_packages: List[str], enclosing_class_id: Optional[str] = None,
+    ) -> Optional[str]:
+        t = erased_type(type_text).strip()
+        while t.endswith("[]"):
+            t = t[:-2]
+        if not t or not all(c.isalnum() or c in "._$" for c in t):
+            return None
+        namespace = self.builder._module_namespace(module_name)
+        module = self.builder._display_module(module_name)
+
+        # Preserve the declared qualification before falling back to the
+        # shared simple-name index.  Java packages commonly contain several
+        # member classes with the same simple name (for example
+        # CommandLine.Builder and HelpFormatter.Builder).  The latter index
+        # is intentionally name-keyed and therefore cannot distinguish
+        # those declarations; using it first silently dispatched a typed
+        # local to whichever Builder happened to be indexed last.
+        exact_names: List[str] = []
+        head, dot, tail = t.partition(".")
+        if head in import_map:
+            exact_names.append(import_map[head] + (f".{tail}" if dot else ""))
+        if dot:
+            exact_names.extend((t, f"{module}.{t}"))
+        else:
+            imported = import_map.get(t)
+            if imported:
+                exact_names.append(imported)
+
+            # A member/local type is resolved relative to the enclosing
+            # lexical type before a package-level type of the same name.
+            # Walk inner-to-outer so ordinary Java shadowing is preserved.
+            if enclosing_class_id and ":" in enclosing_class_id:
+                owner_module, owner_qualname = enclosing_class_id.rsplit(":", 1)
+                owner_module = self.builder._display_module(owner_module)
+                owner_parts = owner_qualname.split(".")
+                for end in range(len(owner_parts), 0, -1):
+                    exact_names.append(
+                        f"{owner_module}.{'.'.join(owner_parts[:end])}.{t}"
+                    )
+            exact_names.append(f"{module}.{t}")
+
+        seen_exact: Set[str] = set()
+        for qualified in exact_names:
+            if qualified in seen_exact:
+                continue
+            seen_exact.add(qualified)
+            tid = self.builder._node_for_dotted(qualified, namespace)
+            if tid and self.builder._nodes[tid].node_type == NodeType.CLASS:
+                return tid
+
+        # JLS 6.4.1: a member type declared by a superclass/superinterface is
+        # inherited and visible by simple name in every subclass body, no
+        # import needed (`class AbstractExtensionContext implements
+        # ExtensionContext` writes the bare `Namespace` for the interface's
+        # own nested `ExtensionContext.Namespace`). Only a bare name reaches
+        # here — a dotted reference is already explicitly qualified. Walking
+        # `_class_ancestors` (nearest declared supertype first, matching
+        # ordinary member shadowing) for a nested type actually declared on
+        # that ancestor is exact, so it runs before the global unique-name
+        # fallback below: without it, any second same-simple-name class
+        # anywhere in a large corpus (here, the unrelated top-level
+        # `org.junit.platform.engine.support.store.Namespace`) makes that
+        # fallback ambiguous and silently drops every call whose argument or
+        # receiver carries the inherited type.
+        if not dot and enclosing_class_id:
+            for ancestor_id in self._class_ancestors(enclosing_class_id):
+                nested_id = f"{ancestor_id}.{t}"
+                nested = self.builder._nodes.get(nested_id)
+                if nested is not None and nested.node_type == NodeType.CLASS:
+                    return nested_id
+
+        # A dotted type is already explicitly qualified. If every exact
+        # package/import/enclosing-type interpretation above missed, do not
+        # discard its qualifier and retry by simple tail name: resolving
+        # `missing.Service` to an unrelated same-package `Service` is a
+        # global/name-shape guess and turns an unknown cast into a wrong edge.
+        if dot:
+            return None
+
+        tid = self.builder._resolve_name(
+            t, module_name, import_map, {}, self._by_module_symbol, strict=True,
+        )
+        if tid and self.builder._nodes[tid].node_type == NodeType.CLASS:
+            return tid
+        for pkg in wildcard_packages:
+            tid = self.builder._node_for_dotted(f"{pkg}.{t}", namespace)
+            if tid is None:
+                tid = self.builder._lookup_qualified(
+                    f"{pkg}.{t}", self._by_module_symbol, namespace
+                )
+            if tid and self.builder._nodes[tid].node_type == NodeType.CLASS:
+                return tid
+        # A functional parameter may carry a nested type name from a
+        # different declaring file's context (for example `Predicate<Bean>`
+        # in a static-imported factory). Preserve strict resolution for
+        # ambiguous names, but recover a project type when the simple name is
+        # globally unique and therefore cannot select a sibling accidentally.
+        # An explicit import that did not resolve above names an external
+        # type (`import java.lang.reflect.Method`), and a bare `java.lang`
+        # name is the JDK type; neither may become an unrelated project class.
+        if t in import_map or t in JAVA_LANG_SIMPLE_TYPES:
+            return None
+        return self.builder._unique_class_by_simple_name(t, namespace)
+
+    def _resolve_receiver(
+        self, obj_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str],
+        local_types: "_LocalScopes", field_types: Dict[str, str],
+        param_types: Dict[str, str],
+        type_param_bounds: Optional[Dict[str, str]] = None,
+    ) -> Tuple[Optional[str], float]:
+        """Resolve a `method_invocation`'s `object` field (already known to
+        be neither None/bare nor `super` — those are handled directly in
+        `_resolve_call`) to `(receiver_class_id, confidence)`.
+
+        Handles: `identifier` (local var / parameter / field / same-package
+        static-class-call receiver), parenthesized/cast receivers,
+        `field_access` (recursively, so
+        `this.userService.findById(id)` unwraps `this.userService` to the
+        field's declared type before resolving `findById` — the exact
+        pattern codegraph-java-deep-dive.md §5.3 calls out), and chained
+        `method_invocation` receivers whose selected source method has a
+        declared return type, and `array_access` whose array expression has a
+        statically-known element type. Lambda/method-reference expressions
+        remain unresolved rather than guessed.
+
+        `type_param_bounds` (P4.12 generic narrowing) rewrites a receiver whose
+        declared type is a method type parameter (`T`) to its concrete upper
+        bound (`<T extends StripeGateway> ... g.charge()` resolves `g` as
+        `StripeGateway`) before type resolution.
+        """
+        bounds = type_param_bounds or {}
+        if obj_node.type == "parenthesized_expression":
+            inner = next((child for child in obj_node.children if child.is_named), None)
+            if inner is None:
+                return None, 0.0
+            return self._resolve_receiver(
+                inner, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+
+        if obj_node.type == "ternary_expression":
+            declared = self._declared_receiver_type_text(
+                obj_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                bounds,
+            )
+            if declared is None:
+                return None, 0.0
+            cid = self._resolve_declared_type(
+                declared, module_name, import_map, wildcard_packages,
+                enclosing_class_id,
+            )
+            return (cid, 0.9) if cid else (None, 0.0)
+
+        if obj_node.type == "cast_expression":
+            type_node = obj_node.child_by_field_name("type")
+            if type_node is None:
+                return None, 0.0
+            declared = self._text(type_node, source)
+            cid = self._resolve_declared_type(
+                self._apply_type_bound(declared, bounds), module_name, import_map,
+                wildcard_packages, enclosing_class_id,
+            )
+            return (cid, 0.9) if cid else (None, 0.0)
+
+        if obj_node.type == "identifier":
+            name = self._text(obj_node, source)
+            local = local_types.type_at(name, obj_node.start_byte)
+            if local is not None:
+                cid = self._resolve_declared_type(
+                    self._apply_type_bound(local, bounds), module_name, import_map,
+                    wildcard_packages, enclosing_class_id,
+                )
+                return (cid, 0.9) if cid else (None, 0.0)
+            if local_types.declared_at(name, obj_node.start_byte):
+                # Shadowed by a local/lambda-parameter of unresolvable type
+                # — must not fall through to an outer param/field/static-type
+                # of the same name, which this identifier no longer names.
+                return None, 0.0
+            if name in param_types:
+                cid = self._resolve_declared_type(
+                    self._apply_type_bound(param_types[name], bounds), module_name,
+                    import_map, wildcard_packages, enclosing_class_id,
+                )
+                return (cid, 0.9) if cid else (None, 0.0)
+            if name in field_types:
+                cid = self._resolve_declared_type(
+                    self._apply_type_bound(field_types[name], bounds), module_name,
+                    import_map, wildcard_packages, enclosing_class_id,
+                )
+                return (cid, 0.9) if cid else (None, 0.0)
+            # `import static Owner.FIELD; FIELD.method()` is a value receiver,
+            # not a bare class name. Recover it only from an explicit static
+            # import whose source owner and declared field both resolve.
+            imported = import_map.get(name)
+            if imported and "." in imported:
+                owner_path, field_name = imported.rsplit(".", 1)
+                owner_id = self._resolve_static_import_class(owner_path, module_name)
+                if owner_id is not None:
+                    declared = self._all_field_types(owner_id).get(field_name)
+                    if declared is not None:
+                        cid = self._resolve_declared_type(
+                            self._apply_type_bound(declared, bounds), module_name,
+                            import_map, wildcard_packages, enclosing_class_id,
+                        )
+                        return (cid, 0.9) if cid else (None, 0.0)
+                    if self._is_enum_constant(owner_id, field_name):
+                        # `import static ...Mode.INCLUDE; INCLUDE.select(x)`:
+                        # a static-imported enum constant is a value of
+                        # exactly its enum (batch 25 — the `select` edge
+                        # itself was never emitted before, not only its
+                        # return type lost).
+                        return owner_id, 0.9
+            # ClassName.staticMethod() — receiver is a type, not a value.
+            cid = self._resolve_declared_type(
+                name, module_name, import_map, wildcard_packages,
+                enclosing_class_id,
+            )
+            if cid:
+                return cid, 0.85
+            return None, 0.0
+
+        if obj_node.type == "field_access":
+            inner_obj = obj_node.child_by_field_name("object")
+            field_node = obj_node.child_by_field_name("field")
+            # Java's qualified enclosing-instance receiver (`Outer.this`)
+            # is represented as a field_access whose field is the `this`
+            # token. It is a value of exactly `Outer`, not a field lookup.
+            # Resolve only a real lexical owner of the current class; this
+            # prevents an arbitrary `Unrelated.this` spelling from becoming
+            # a source receiver.
+            if (
+                inner_obj is not None and inner_obj.type == "identifier"
+                and field_node is not None and field_node.type == "this"
+                and enclosing_class_id is not None
+            ):
+                requested = self._text(inner_obj, source)
+                for outer_id in self._lexical_outer_class_ids(enclosing_class_id):
+                    outer = self.builder._nodes.get(outer_id)
+                    if outer is not None and outer.name == requested:
+                        return outer_id, 0.9
+            # A dotted static type receiver has the same CST shape as value
+            # field access: `Publication.Status.values()` presents
+            # `Publication.Status` as a field_access object. Resolve the
+            # complete qualified text as a source type first. Strict declared
+            # type lookup prevents an ordinary `instance.field` expression
+            # from becoming a type unless that exact qualification exists.
+            qualified_type = self._resolve_declared_type(
+                self._text(obj_node, source), module_name, import_map,
+                wildcard_packages, enclosing_class_id,
+            )
+            if qualified_type is not None:
+                return qualified_type, 0.85
+            if field_node is None:
+                return None, 0.0
+            field_name = self._text(field_node, source)
+            if inner_obj is not None and inner_obj.type == "this":
+                if enclosing_class_id is None:
+                    return None, 0.0
+                own_fields = self._all_field_types(enclosing_class_id)
+                if field_name in own_fields:
+                    cid = self._resolve_declared_type(
+                        self._apply_type_bound(own_fields[field_name], bounds),
+                        module_name, import_map, wildcard_packages,
+                        enclosing_class_id,
+                    )
+                    return (cid, 0.9) if cid else (None, 0.0)
+                return None, 0.0
+            if inner_obj is None:
+                return None, 0.0
+            base_id, base_conf = self._resolve_receiver(
+                inner_obj, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types, type_param_bounds,
+            )
+            if base_id is None:
+                return None, 0.0
+            base_fields = self._all_field_types(base_id)
+            if field_name in base_fields:
+                # `bounds` was collected for `enclosing_class_id`'s own
+                # `<T extends ...>` (P4.12 generic narrowing). `base_id` here
+                # is whichever class `inner_obj` resolved to, which may be a
+                # *different* class than `enclosing_class_id` (a chained
+                # field access, e.g. `helper.gateway.charge()`). That other
+                # class may declare its own unrelated type parameter that
+                # happens to share the same bare name (`T` is the idiomatic
+                # single-letter generic name), so blindly reusing `bounds`
+                # here would rebind its field to the caller's binding by
+                # name collision alone rather than its own — a correctness
+                # bug, not just an over-approximation. Bounds only apply
+                # when the field genuinely belongs to the class they were
+                # collected for; a self-referential chain back to the same
+                # class (`base_id == enclosing_class_id`) is the one case
+                # where reusing them is still correct.
+                hop_bounds = bounds if base_id == enclosing_class_id else {}
+                cid = self._resolve_declared_type(
+                    self._apply_type_bound(base_fields[field_name], hop_bounds),
+                    module_name, import_map, wildcard_packages,
+                    enclosing_class_id,
+                )
+                return (cid, min(base_conf, 0.9)) if cid else (None, 0.0)
+            if self._is_enum_constant(base_id, field_name):
+                # `Mode.INCLUDE.select(x)`: a declared enum constant is a
+                # value receiver of exactly its enum type (batch 25).
+                return base_id, min(base_conf, 0.9)
+            return None, 0.0
+
+        if obj_node.type == "array_access":
+            array_node = obj_node.child_by_field_name("array")
+            if array_node is None:
+                return None, 0.0
+            array_type = self._declared_receiver_type_text(
+                array_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types, bounds,
+            )
+            if array_type is None:
+                return None, 0.0
+            erased_array = erased_type(array_type).strip()
+            if not erased_array.endswith("[]"):
+                return None, 0.0
+            element_type = erased_array[:-2].strip()
+            if not element_type or element_type.endswith("[]"):
+                # One access into a multidimensional array still yields an
+                # array, not a source class receiver with ordinary methods.
+                return None, 0.0
+            cid = self._resolve_declared_type(
+                self._apply_type_bound(element_type, bounds), module_name,
+                import_map, wildcard_packages, enclosing_class_id,
+            )
+            confidence = 0.75 if array_node.type == "method_invocation" else 0.9
+            return (cid, confidence) if cid else (None, 0.0)
+
+        if obj_node.type == "method_invocation":
+            return_type = self._generic_method_invocation_return_type(
+                obj_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types, bounds,
+            )
+            if return_type is None:
+                return None, 0.0
+            return_bounds = (
+                bounds
+                if self._method_return_uses_current_type_bounds(
+                    obj_node, return_type, source, module_name, enclosing_class_id,
+                    import_map, wildcard_packages, local_types, field_types,
+                    param_types, bounds,
+                )
+                else {}
+            )
+            cid = self._resolve_declared_type(
+                self._apply_type_bound(return_type, return_bounds),
+                module_name, import_map, wildcard_packages,
+                enclosing_class_id,
+            )
+            return (cid, 0.75) if cid else (None, 0.0)
+
+        return None, 0.0
+
+    def _method_return_uses_current_type_bounds(
+        self, method_node, return_type: str, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        field_types: Dict[str, str], param_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> bool:
+        """Whether a method-chain return type may use current generic bounds.
+
+        `Box<T> box; box.value()` may bind `T` from the current scope. But
+        `helper.box.value()` must not bind `Helper`'s own `T` using the
+        caller's unrelated `T`, even when the names collide.
+        """
+        returned = erased_type(return_type).strip()
+        while returned.endswith("[]"):
+            returned = returned[:-2]
+        if returned not in type_param_bounds:
+            return False
+        receiver_node = method_node.child_by_field_name("object")
+        if receiver_node is None:
+            return False
+        receiver_type = self._declared_receiver_type_text(
+            receiver_node, source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, field_types, param_types,
+            type_param_bounds,
+        )
+        if receiver_type is None:
+            return False
+        receiver_args = {
+            erased_type(arg).strip()
+            for arg in self._generic_type_arguments(receiver_type)
+        }
+        if returned not in receiver_args:
+            return False
+        return self._receiver_expression_uses_current_type_bounds(
+            receiver_node, source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, field_types, param_types,
+            type_param_bounds,
+        )
+
+    def _receiver_expression_uses_current_type_bounds(
+        self, obj_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        field_types: Dict[str, str], param_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> bool:
+        if obj_node.type == "identifier":
+            name = self._text(obj_node, source)
+            if local_types.type_at(name, obj_node.start_byte) is not None:
+                return True
+            if local_types.declared_at(name, obj_node.start_byte):
+                # Shadowed by a local/lambda-parameter of unresolvable type
+                # — must not fall through to an outer param/field of the
+                # same name.
+                return False
+            return name in param_types or name in field_types
+        if obj_node.type == "field_access":
+            inner_obj = obj_node.child_by_field_name("object")
+            if inner_obj is None:
+                return False
+            if inner_obj.type == "this":
+                return enclosing_class_id is not None
+            base_id, _ = self._resolve_receiver(
+                inner_obj, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+            return base_id is not None and base_id == enclosing_class_id
+        if obj_node.type == "method_invocation":
+            return_type = self._generic_method_invocation_return_type(
+                obj_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+            return bool(
+                return_type is not None
+                and self._method_return_uses_current_type_bounds(
+                    obj_node, return_type, source, module_name,
+                    enclosing_class_id, import_map, wildcard_packages,
+                    local_types, field_types, param_types, type_param_bounds,
+                )
+            )
+        return False
+
+    def _declared_receiver_type_text(
+        self, obj_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        field_types: Dict[str, str], param_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> Optional[str]:
+        """Declared type text for a value receiver, preserving generics."""
+        if obj_node.type in ("string_literal", "text_block"):
+            # A string literal (or text block) receiver is a `java.lang.String`
+            # by JLS 3.10.5 — nothing else can ever be the receiver of
+            # `"...".formatted(a, b)` / `"...".trim()`. This was the missing
+            # receiver case behind JUnit5 FP/FN catalog #16476
+            # (`assertTrue(cond, "...".formatted(first, second))`): with no
+            # declared type for the literal, the chained call's return stayed
+            # unknown, so `_narrow_candidates_by_known_arg_types` could not
+            # exclude the `Supplier<String>` sibling and the call fanned out
+            # across `assertTrue(boolean,String)`/`(boolean,Supplier)` at the
+            # capped 0.55 confidence. The `String` member returns themselves
+            # come from `JAVA_GENERIC_METHOD_STUB_RETURNS`.
+            return "String"
+        if obj_node.type == "class_literal":
+            # `Type.class` is a `Class<Type>` receiver. Its element type is
+            # irrelevant to fixed JDK `Class` member returns such as
+            # `getDeclaredMethod`, but recognizing the receiver lets that
+            # exact declaration participate in contextual constructor typing.
+            return "Class"
+        if obj_node.type == "cast_expression":
+            # JLS 15.16: the type of a cast expression is the cast type —
+            # `((MyId) deserialized).getValue()` (batch 26). `_resolve_receiver`
+            # already read it for the call edge; the fluent/argument typing
+            # path lost it.
+            type_node = obj_node.child_by_field_name("type")
+            return self._text(type_node, source) if type_node is not None else None
+        if obj_node.type == "parenthesized_expression":
+            inner = next((child for child in obj_node.children if child.is_named), None)
+            if inner is None:
+                return None
+            return self._declared_receiver_type_text(
+                inner, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+
+        if obj_node.type == "ternary_expression":
+            consequence = obj_node.child_by_field_name("consequence")
+            alternative = obj_node.child_by_field_name("alternative")
+            if consequence is None or alternative is None:
+                return None
+            branch_types = [
+                self._declared_receiver_type_text(
+                    branch, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, field_types, param_types,
+                    type_param_bounds,
+                )
+                for branch in (consequence, alternative)
+            ]
+            if any(branch_type is None for branch_type in branch_types):
+                return None
+            # A ternary whose two branches have precisely the same declared
+            # type needs no least-upper-bound inference.  This is especially
+            # useful for external generic receivers such as
+            # `Stream<JavaPackage>`: source identity cannot resolve `Stream`,
+            # but retaining equal text is exact.  Differing branch types still
+            # remain unresolved rather than being guessed.
+            if branch_types[0] == branch_types[1]:
+                return branch_types[0]
+            # One branch may spell a JDK owner as its declaring file imports
+            # it (`java.util.stream.Stream<pkg.JavaPackage>` from a source
+            # method's canonicalized return) while the other comes from an
+            # exact JDK stub (`Stream<JavaPackage>`).  Both name one type;
+            # unify them structurally without guessing a least upper bound.
+            equivalent = self._equivalent_type_texts(
+                branch_types[0], branch_types[1], module_name, import_map,
+                wildcard_packages, enclosing_class_id,
+            )
+            if equivalent is not None:
+                return equivalent
+            branch_ids = [
+                self._resolve_declared_type(
+                    branch_type, module_name, import_map, wildcard_packages,
+                    enclosing_class_id,
+                )
+                for branch_type in branch_types
+            ]
+            if branch_ids[0] is None or branch_ids[0] != branch_ids[1]:
+                return None
+            return branch_types[0]
+
+        if obj_node.type == "identifier":
+            name = self._text(obj_node, source)
+            local = local_types.type_at(name, obj_node.start_byte)
+            if local is not None:
+                return self._apply_type_bound(local, type_param_bounds)
+            if local_types.declared_at(name, obj_node.start_byte):
+                # Shadowed by a local/lambda-parameter of unresolvable type
+                # — must not fall through to an outer param/field of the
+                # same name, which this identifier no longer names here.
+                return None
+            if name in param_types:
+                return self._apply_type_bound(param_types[name], type_param_bounds)
+            if name in field_types:
+                return self._apply_type_bound(field_types[name], type_param_bounds)
+            # An explicitly static-imported source field or enum constant
+            # (`import static ...EnumSource.Mode.INCLUDE; INCLUDE.select(x)`)
+            # is a value receiver with a declared type — batch 25: the
+            # chained source call's `boolean` return used to stay unknown,
+            # so `assertTrue(INCLUDE.select(...))` fanned out to the
+            # `BooleanSupplier` sibling. Same exact-import-only lookup the
+            # argument path already trusts; wildcard static imports stay
+            # unresolved.
+            imported = self._static_imported_field_arg_type(
+                obj_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, param_types, field_types,
+            )
+            if imported is not None:
+                return imported
+            # A value declaration always wins above, but an otherwise-unbound
+            # identifier may be a type receiver (`CommandLine.builder()`).
+            # Preserve that type text so the source method's declared return
+            # type can seed the next fluent receiver.  `_resolve_declared_type`
+            # keeps this source-only and import-aware; an unknown/external
+            # type therefore remains unresolved instead of becoming a global
+            # simple-name guess.
+            if self._resolve_declared_type(
+                name, module_name, import_map, wildcard_packages,
+            ) is not None:
+                return name
+            return None
+
+        if obj_node.type == "field_access":
+            inner_obj = obj_node.child_by_field_name("object")
+            field_node = obj_node.child_by_field_name("field")
+            if field_node is None:
+                return None
+            field_name = self._text(field_node, source)
+            if inner_obj is not None and inner_obj.type == "this":
+                if enclosing_class_id is None:
+                    return None
+                return self._all_field_types(enclosing_class_id).get(field_name)
+            if inner_obj is None:
+                return None
+            base_id, _ = self._resolve_receiver(
+                inner_obj, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+            if base_id is not None:
+                declared_field = self._all_field_types(base_id).get(field_name)
+                if declared_field is not None:
+                    return declared_field
+                if self._is_enum_constant(base_id, field_name):
+                    # `Mode.INCLUDE.select(x)`: every declared enum constant
+                    # has exactly its enum type (batch 25; same metadata-
+                    # backed rule `_source_static_field_arg_type` applies to
+                    # an enum-constant *argument*). Spelled as the call site
+                    # spells the enum, which already resolved to `base_id`.
+                    return self._text(inner_obj, source)
+            # A dotted nested type has the same CST shape as a field access:
+            # `EventPublication.Status.values()` presents
+            # `EventPublication.Status` here.  Only accept the complete text
+            # when strict source type resolution succeeds; an ordinary
+            # unresolved `object.field` remains unknown.
+            qualified_type = self._text(obj_node, source)
+            if self._resolve_declared_type(
+                qualified_type, module_name, import_map, wildcard_packages,
+                enclosing_class_id,
+            ) is not None:
+                return qualified_type
+            return None
+
+        if obj_node.type == "array_access":
+            # Preserve the element's declared type for a chained source
+            # return lookup: `visits[0].getPet().getId()`.  `_resolve_receiver`
+            # already resolves `visits[0]` well enough to emit `getPet`, but
+            # the outer hop asks this text helper for the inner call's
+            # receiver type.  Without the symmetric array case here, that
+            # lookup stopped at the inner edge and silently dropped `getId`.
+            array_node = obj_node.child_by_field_name("array")
+            if array_node is None:
+                return None
+            array_type = self._declared_receiver_type_text(
+                array_node, source, module_name, enclosing_class_id,
+                import_map, wildcard_packages, local_types, field_types,
+                param_types, type_param_bounds,
+            )
+            if array_type is None:
+                return None
+            erased_array = erased_type(array_type).strip()
+            if not erased_array.endswith("[]"):
+                return None
+            return erased_array[:-2].strip() or None
+
+        if obj_node.type == "method_invocation":
+            return self._generic_method_invocation_return_type(
+                obj_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+        return None
+
+
+    def _generic_method_invocation_return_type(
+        self, call_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        field_types: Dict[str, str], param_types: Dict[str, str],
+        type_param_bounds: Dict[str, str],
+    ) -> Optional[str]:
+        """Best-effort generic return type for chained receiver calls.
+
+        Source-declared generic methods are resolved from the receiver's raw
+        class and the target method's persisted return type, then type
+        variables are substituted from the receiver's actual type arguments
+        (`Box<? extends Gateway>.value() -> Gateway`). JDK/container methods
+        whose declarations are outside the analyzed source use a small
+        signature table with the same substitution path.
+        """
+        name_node = call_node.child_by_field_name("name")
+        receiver_node = call_node.child_by_field_name("object")
+        if name_node is None:
+            return None
+        method_name = self._text(name_node, source)
+        if (
+            method_name in JAVA_OBJECT_MEMBER_RETURNS
+            and self._count_args(call_node.child_by_field_name("arguments")) == 0
+        ):
+            # `x.toString()` is a `String` for every `x` (JLS 4.3.2), whether
+            # or not the receiver or an override is resolvable.
+            return JAVA_OBJECT_MEMBER_RETURNS[method_name]
+        if method_name == "assertThat":
+            # AssertJ's `assertThat(actual)` has no source declaration to
+            # resolve structurally (external library); recognize it by name
+            # + owner so a following fluent `hasValueSatisfying`/`satisfies`/
+            # `allSatisfy` lambda still learns `actual`'s real element type
+            # instead of losing inference at this external hop. Applies to
+            # both the bare, statically-imported call and the explicitly
+            # qualified `Assertions.assertThat(actual)` form — both reach
+            # this same early check via `receiver_node` below.
+            assertj_return = self._assertj_assertthat_return_type(
+                call_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, param_types, field_types,
+            )
+            if assertj_return is not None:
+                return assertj_return
+        if receiver_node is None or receiver_node.type == "this":
+            if receiver_node is None and method_name in import_map:
+                # A bare call can be an explicitly static-imported source
+                # factory. Its result type belongs to the imported class, not
+                # to the caller's enclosing class. Without this branch,
+                # `import static Builder.request; request().step()` resolves
+                # the root call but loses every fluent hop, especially when
+                # the factory lives in another build module.
+                resolved_import = import_map[method_name]
+                owner_path = ".".join(resolved_import.split(".")[:-1])
+                imported_owner = self._resolve_static_import_class(
+                    owner_path, module_name,
+                )
+                if imported_owner is not None and ":" in imported_owner:
+                    owner_module, owner_qualname = imported_owner.rsplit(":", 1)
+                    receiver_type = (
+                        f"{self.builder._display_module(owner_module)}."
+                        f"{owner_qualname}"
+                    )
+                else:
+                    receiver_type = None
+            else:
+                receiver_type = None
+            if receiver_type is None:
+                if enclosing_class_id is None or ":" not in enclosing_class_id:
+                    return None
+                # A chained receiver may itself be a bare/this source call:
+                # `getOptions().hasOption(x)`. The call's dispatch root is the
+                # enclosing class (plus its ancestors), even though there is no
+                # explicit receiver CST node from which to read a declared type.
+                # Preserve the exact class id as a dotted type so the existing
+                # strict source-method/overload/return-context path can be reused
+                # without a global simple-name fallback.
+                owner_module, owner_qualname = enclosing_class_id.rsplit(":", 1)
+                receiver_type = (
+                    f"{self.builder._display_module(owner_module)}.{owner_qualname}"
+                )
+        elif receiver_node.type == "object_creation_expression":
+            # One precise C08 continuation: after `new T(...).step(args)`
+            # has a uniquely selected source method, its declared return may
+            # seed the immediately following hop. The created type is still
+            # resolved strictly; `_generic_return_type_from_source_method`
+            # below refuses ambiguous overload targets, so this does not turn
+            # unknown root-new calls into chain fan-out.
+            type_node = receiver_node.child_by_field_name("type")
+            if type_node is None:
+                return None
+            created_type = self._text(type_node, source)
+            if self._resolve_declared_type(
+                created_type, module_name, import_map, wildcard_packages,
+                enclosing_class_id,
+            ) is None:
+                return None
+            receiver_type = created_type
+        else:
+            receiver_type = self._declared_receiver_type_text(
+                receiver_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, field_types, param_types,
+                type_param_bounds,
+            )
+        if receiver_type is None:
+            # Static JDK factories have no source class node, hence cannot
+            # supply a declared receiver type.  Consult the intentionally
+            # tiny exact table before giving up on a following fluent hop.
+            return self._external_static_call_return_type(
+                call_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, param_types, field_types,
+            )
+        receiver_args = self._generic_type_arguments(receiver_type)
+        raw_simple = erased_type(receiver_type).strip().split(".")[-1]
+
+        # `BeanFactory.getBean(Class<T>)` (JLS-external, Spring-documented
+        # contract — see `SPRING_BEAN_CONTAINER_TYPES`) returns exactly the
+        # argument's own `Class<T>` literal type. Restricted to the single-
+        # `Class<T>`-literal overload: `getBean(String)`/`getBean(String,
+        # Class<T>)` name a bean by id, not by this argument, and stay
+        # unresolved rather than guessed.
+        if raw_simple in SPRING_BEAN_CONTAINER_TYPES and method_name == "getBean":
+            args_node = call_node.child_by_field_name("arguments")
+            args = argument_nodes(args_node) if args_node is not None else []
+            if len(args) == 1 and args[0].type == "class_literal":
+                literal = next(
+                    (child for child in args[0].children if child.is_named), None,
+                )
+                if literal is not None:
+                    return self._text(literal, source)
+            return None
+
+        # `Optional<T>.orElse(fallback)` returns T only when the fallback is
+        # assignable to T (or is null).  Unlike `get`/`orElseThrow`, blindly
+        # substituting T would hide an invalid or otherwise unknown fallback
+        # and could give a following `var` receiver a wrong source target.
+        # Keep this to one exact argument and the normal overload-compatible
+        # type check; poly expressions remain unresolved.
+        if raw_simple == "Optional" and method_name == "orElse" and len(receiver_args) == 1:
+            args_node = call_node.child_by_field_name("arguments")
+            fallback_types = self._infer_contextual_arg_types(
+                args_node, source, module_name, enclosing_class_id, import_map,
+                wildcard_packages, local_types, param_types, field_types,
+                type_param_bounds,
+            )
+            if fallback_types is not None and len(fallback_types) == 1:
+                element_type = receiver_args[0]
+                fallback_type = fallback_types[0]
+                ctx = _ImportContext(
+                    module_name, import_map, wildcard_packages, enclosing_class_id,
+                )
+                if fallback_type == "null" or self._types_compatible(
+                    erased_type(element_type), fallback_type, ctx, ctx,
+                ):
+                    return element_type
+            return None
+
+        # A directly invoked source method in an Optional mapper has a
+        # declared result even when the mapper's external input type cannot
+        # be reconstructed. Preserve only that exact expression-lambda case
+        # so `optional.map(x -> sourceFactory(x)).orElseThrow()` can type a
+        # following `var`; arbitrary mapper bodies remain unresolved.
+        # The same exact expression-lambda rule types `Stream.map(x ->
+        # sourceCall(x))` as `Stream<R>`, and `flatMap` when the body's
+        # declared result is itself the container type.
+        if raw_simple in {"Optional", "Stream"} and method_name in {"map", "flatMap"}:
+            args_node = call_node.child_by_field_name("arguments")
+            args = argument_nodes(args_node)
+            if len(args) == 1 and args[0].type == "lambda_expression":
+                body = args[0].child_by_field_name("body")
+                if body is not None and body.type in {
+                    "method_invocation", "object_creation_expression",
+                }:
+                    mapped = self._declared_receiver_type_text(
+                        body, source, module_name, enclosing_class_id, import_map,
+                        wildcard_packages, local_types, field_types, param_types,
+                        type_param_bounds,
+                    )
+                    if mapped is not None:
+                        if method_name == "map":
+                            return f"{raw_simple}<{mapped}>"
+                        if erased_type(mapped).rsplit(".", 1)[-1] == raw_simple:
+                            return mapped
+            # A static method reference (`Type::staticMethod`) as the sole
+            # mapper argument has a declared result the same way an
+            # expression-lambda body does above; `Stream.map`/`.flatMap`
+            # already resolve a method reference argument for the *unbound-
+            # instance* shape (`Type::instanceMethod`, zero extra params,
+            # element itself the receiver) further below, but not this
+            # *static*, one-parameter shape (`Optional.map(Owner::create)`,
+            # the real `AdditionalDiscoverySelectors::selectDirectories`
+            # JUnit5 pattern) for either container -- required one static
+            # candidate, exactly as conservative as the lambda case (an
+            # overloaded or ambiguous reference stays unresolved).
+            if len(args) == 1 and args[0].type == "method_reference":
+                ref_node = args[0]
+                named = [child for child in ref_node.children if child.is_named]
+                terminal = next(
+                    (child for child in reversed(ref_node.children)
+                     if child.type in {"identifier", "new"}),
+                    None,
+                )
+                if named and terminal is not None and terminal.type != "new":
+                    owner_id = self._resolve_declared_type(
+                        self._text(named[0], source), module_name, import_map,
+                        wildcard_packages, enclosing_class_id,
+                    )
+                    if owner_id is not None:
+                        candidates = [
+                            candidate for candidate in self._members_named(
+                                owner_id, self._text(terminal, source),
+                                search_ancestors=True,
+                            )
+                            if (
+                                self._is_static_member(candidate)
+                                and len(self._param_type_lists.get(candidate, [])) == 1
+                            )
+                        ]
+                        if len(candidates) == 1:
+                            candidate = self.builder._nodes.get(candidates[0])
+                            result_type = (
+                                candidate.metadata.get("java_return_type")
+                                if candidate is not None else None
+                            )
+                            if isinstance(result_type, str) and result_type != "void":
+                                if method_name == "map":
+                                    return f"{raw_simple}<{result_type}>"
+                                if erased_type(result_type).rsplit(".", 1)[-1] == raw_simple:
+                                    return result_type
+
+        # `Function<T,R>.andThen(f)` consumes R and returns `Function<T,V>`.
+        # The bounded `Class::getName` case is sufficient for the source
+        # chain `toEventType().andThen(Class::getName).andThen(name -> ...)`;
+        # other method references remain unknown instead of guessing V.
+        if raw_simple == "Function" and method_name == "andThen" and len(receiver_args) == 2:
+            args_node = call_node.child_by_field_name("arguments")
+            arg_nodes = argument_nodes(args_node)
+            if len(arg_nodes) == 1 and arg_nodes[0].type == "method_reference":
+                named = [child for child in arg_nodes[0].children if child.is_named]
+                terminal = next(
+                    (child for child in reversed(arg_nodes[0].children)
+                     if child.type in {"identifier", "new"}),
+                    None,
+                )
+                if (
+                    len(named) >= 1
+                    and terminal is not None
+                    and self._text(named[0], source) == "Class"
+                    and self._text(terminal, source) == "getName"
+                ):
+                    return f"Function<{receiver_args[0]},String>"
+
+        source_return = self._generic_return_type_from_source_method(
+            receiver_type, receiver_args, method_name, call_node, source,
+            module_name, import_map, wildcard_packages, local_types, field_types,
+            param_types, enclosing_class_id,
+        )
+        if source_return is not None:
+            return source_return
+        if raw_simple in JAVA_TIME_TEMPORAL_TYPES:
+            if (
+                method_name in JAVA_TIME_SELF_RETURNING_EXACT
+                or method_name.startswith(JAVA_TIME_SELF_RETURNING_PREFIXES)
+            ):
+                return raw_simple
+            converted = JAVA_TIME_CONVERSION_RETURNS.get((raw_simple, method_name))
+            if converted is not None:
+                return converted
+        if receiver_node is None and enclosing_class_id is not None:
+            # A bare call in a non-static nested class may resolve through an
+            # enclosing instance (`Inner.this` semantics). `_resolve_call`
+            # already emits that root edge, but `var`/fluent propagation used
+            # to inspect only the inner class and therefore lost the outer
+            # method's declared return type. Walk lexical owners nearest-first
+            # after the current class has failed; a static nested boundary has
+            # no enclosing instance beyond itself.
+            #
+            # Batch 25: a *static* nested class has no enclosing instance,
+            # but its bare calls still reach every lexically enclosing
+            # class's `static` methods (JLS 8.1.3 / 15.12.1) —
+            # `assumeTrue(makeReadOnly(dir))` inside `static class
+            # ReadOnlyFileTestCase` calls the outer test class's `private
+            # static boolean makeReadOnly(File)`. The walk used to stop dead
+            # at the static boundary, so the argument's `boolean` return
+            # stayed unknown and the call fanned out to the
+            # `assumeTrue(BooleanSupplier)` sibling at 0.55. Once any class
+            # on the way up is static, only static outer members remain
+            # reachable, so the walk continues in static-only mode instead
+            # of breaking.
+            current = self.builder._nodes.get(enclosing_class_id)
+            static_only = (
+                current is not None
+                and "static" in current.metadata.get("modifiers", ())
+            )
+            for outer_id in self._lexical_outer_class_ids(enclosing_class_id):
+                outer_module, outer_qualname = outer_id.rsplit(":", 1)
+                outer_type = (
+                    f"{self.builder._display_module(outer_module)}.{outer_qualname}"
+                )
+                source_return = self._generic_return_type_from_source_method(
+                    outer_type, [], method_name, call_node, source,
+                    module_name, import_map, wildcard_packages, local_types,
+                    field_types, param_types, enclosing_class_id,
+                    static_only=static_only,
+                )
+                if source_return is not None:
+                    return source_return
+                outer = self.builder._nodes.get(outer_id)
+                if outer is not None and "static" in outer.metadata.get("modifiers", ()):
+                    static_only = True
+
+        external_static_return = self._external_static_call_return_type(
+            call_node, source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, param_types, field_types,
+        )
+        if external_static_return is not None:
+            return external_static_return
+
+        # `Stream.map(Function<T,R>)` changes the element type to the
+        # functional argument's declared result type. Preserve that exact R
+        # for a following fluent hop when the callable is a typed
+        # local/parameter/field; unknown lambdas and overloaded references
+        # remain unresolved rather than guessed.
+        if raw_simple == "Stream" and method_name in {"map", "flatMap"}:
+            args_node = call_node.child_by_field_name("arguments")
+            arg_nodes = argument_nodes(args_node)
+            if len(arg_nodes) == 1 and arg_nodes[0].type == "identifier":
+                argument_name = self._text(arg_nodes[0], source)
+                functional_type = (
+                    local_types.type_at(argument_name, arg_nodes[0].start_byte)
+                    or param_types.get(argument_name)
+                    or field_types.get(argument_name)
+                )
+                functional_args = (
+                    self._generic_type_arguments(functional_type)
+                    if functional_type is not None else []
+                )
+                if len(functional_args) >= 2:
+                    result_type = functional_args[-1]
+                    if method_name == "flatMap" and erased_type(result_type).rsplit(".", 1)[-1] == "Stream":
+                        return result_type
+                    if method_name == "map":
+                        return f"Stream<{result_type}>"
+            if len(arg_nodes) == 1 and arg_nodes[0].type == "method_reference":
+                ref_node = arg_nodes[0]
+                named = [child for child in ref_node.children if child.is_named]
+                terminal = next(
+                    (child for child in reversed(ref_node.children)
+                     if child.type in {"identifier", "new"}),
+                    None,
+                )
+                if named and terminal is not None and terminal.type != "new":
+                    owner_id = self._resolve_declared_type(
+                        self._text(named[0], source), module_name, import_map,
+                        wildcard_packages, enclosing_class_id,
+                    )
+                    if owner_id is not None:
+                        candidates = [
+                            candidate for candidate in self._members_named(
+                                owner_id, self._text(terminal, source),
+                                search_ancestors=True,
+                            )
+                            if len(self._param_type_lists.get(candidate, [])) == 0
+                        ]
+                        if len(candidates) == 1:
+                            candidate = self.builder._nodes.get(candidates[0])
+                            result_type = (
+                                candidate.metadata.get("java_return_type")
+                                if candidate is not None else None
+                            )
+                            if isinstance(result_type, str) and result_type != "void":
+                                if method_name == "flatMap" and (
+                                    erased_type(result_type).rsplit(".", 1)[-1] == "Stream"
+                                ):
+                                    return result_type
+                                if method_name == "map":
+                                    return f"Stream<{result_type}>"
+
+        # `getClass()` is final on `java.lang.Object`, so every receiver
+        # yields `Class<?>` and no source class can redeclare it.
+        if method_name == "getClass" and self._count_args(
+            call_node.child_by_field_name("arguments")
+        ) == 0:
+            return "java.lang.Class<?>"
+
+        stub_return = JAVA_GENERIC_METHOD_STUB_RETURNS.get((raw_simple, method_name))
+        receiver_class_id = self._resolve_declared_type(
+            receiver_type, module_name, import_map, wildcard_packages,
+            enclosing_class_id,
+        )
+        if receiver_class_id is not None:
+            # The stub table describes JDK declarations. A source class that
+            # merely shares a JDK simple name (`Class`, `Method`) has already
+            # had its own members consulted above and must not inherit JDK
+            # facts *by name*. Two exact, declaration-backed cases remain
+            # (batch 26), both gated on the hierarchy declaring no member of
+            # that name at all:
+            if self._members_named(receiver_class_id, method_name, search_ancestors=True):
+                return None
+            arg_count = self._count_args(call_node.child_by_field_name("arguments"))
+            # JLS 8.10.3: a record's implicit accessor `exitCode()` returns
+            # the component's declared type. The extractor records
+            # components as `record_components`; there is no method node.
+            record_node = self.builder._nodes.get(receiver_class_id)
+            components = record_node.metadata.get("record_components", {}) if record_node else {}
+            if arg_count == 0 and method_name in components:
+                component_type = components[method_name]
+                if erased_type(component_type).strip() in self._class_type_params.get(receiver_class_id, []):
+                    return None
+                return component_type
+            # JLS 8.4.8: a source class inherits its external superclass's
+            # members — `exception.getMessage()` on a project exception
+            # extending `RuntimeException` is `Throwable.getMessage()`. Only
+            # the nearest external ancestors the declaring files actually
+            # import (or `java.lang`) are consulted, with the same fixed-
+            # return facts; a generic stub whose result is the JDK class's
+            # own type variable stays unknown (no receiver arguments here).
+            for external_simple in self._external_ancestor_simple_names(receiver_class_id):
+                inherited = JAVA_GENERIC_METHOD_STUB_RETURNS.get((external_simple, method_name))
+                if inherited is None and external_simple in JAVA_THROWABLE_SIMPLE_TYPES:
+                    inherited = JAVA_GENERIC_METHOD_STUB_RETURNS.get(("Throwable", method_name))
+                if inherited is None:
+                    continue
+                if erased_type(inherited).strip() in JAVA_GENERIC_TYPE_PARAM_STUBS.get(external_simple, []):
+                    return None
+                return inherited
+            return None
+        if stub_return is None:
+            return None
+        type_params = JAVA_GENERIC_TYPE_PARAM_STUBS.get(raw_simple, [])
+        return self._substitute_generic_return_type(
+            stub_return, type_params, receiver_args,
+        )
+
+    def _external_ancestor_simple_names(self, class_id: str) -> List[str]:
+        """Simple names of the external (JDK/library) supertypes a source
+        class reaches through its own or any source ancestor's `extends`/
+        `implements` clause, nearest first — each spelling resolved in its
+        declaring file's import context (`_external_type_name`), never by
+        simple name alone."""
+        out: List[str] = []
+        for owner_id in (class_id, *self._class_ancestors(class_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_fqn = self._external_type_name(erased_type(declared_super).strip(), owner_ctx)
+                if super_fqn is None:
+                    continue
+                simple = super_fqn.rsplit(".", 1)[-1]
+                if simple not in out:
+                    out.append(simple)
+        return out
+
+    def _assertj_assertthat_return_type(
+        self, call_node, source: bytes, module_name: str,
+        enclosing_class_id: Optional[str], import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        param_types: Dict[str, str], field_types: Dict[str, str],
+    ) -> Optional[str]:
+        """Wrapper type for `org.assertj.core.api.Assertions.assertThat
+        (actual)`, derived from `actual`'s own declared type text.
+
+        AssertJ's real `assertThat` overload set (dozens of `Optional`/
+        `Map`/`Iterable`/generic-`Object` overloads, each returning a
+        distinct `*Assert` wrapper) has no source declaration for this
+        resolver to look up structurally. Recognizing just the calling
+        convention -- one argument, whose type is already known here -- is
+        enough to hand a following fluent `hasValueSatisfying`/`satisfies`/
+        `allSatisfy` lambda its real element type one hop later, without
+        emitting a fabricated call edge to AssertJ itself (this function
+        only ever feeds `_invocation_functional_target_type`'s lambda-typing
+        path, never `_resolve_call`).
+        """
+        receiver_node = call_node.child_by_field_name("object")
+        if receiver_node is None:
+            owner_fqn = import_map.get("assertThat")
+            if owner_fqn is not None:
+                owner_path = owner_fqn.rsplit(".", 1)[0]
+            else:
+                # `assertThat` almost always reaches a file through
+                # `import static org.assertj.core.api.Assertions.*;`, not
+                # an explicit single import of the one method — `import_map`
+                # (single imports only) misses this convention entirely,
+                # silently disabling this whole AssertJ lambda-typing path
+                # for every file that uses it (spring-modulith benchmark
+                # finding: 119/~575 files, 0 using the single-name form).
+                # `enclosing_class_id`'s own file carries the same static
+                # wildcard imports as the call site inside it.
+                enclosing = (
+                    self.builder._nodes.get(enclosing_class_id)
+                    if enclosing_class_id else None
+                )
+                wildcard_classes = (
+                    self._static_wildcard_by_file.get(enclosing.file_path, [])
+                    if enclosing is not None else []
+                )
+                owner_path = next(
+                    (o for o in ASSERTJ_ASSERT_FACTORY_OWNERS if o in wildcard_classes),
+                    None,
+                )
+                if owner_path is None:
+                    return None
+        elif receiver_node.type == "identifier":
+            owner_path = import_map.get(self._text(receiver_node, source))
+            if owner_path is None:
+                return None
+        else:
+            return None
+        if owner_path not in ASSERTJ_ASSERT_FACTORY_OWNERS:
+            return None
+        args_node = call_node.child_by_field_name("arguments")
+        args = argument_nodes(args_node) if args_node is not None else []
+        if len(args) != 1:
+            return None
+        actual_type = self._declared_receiver_type_text(
+            args[0], source, module_name, enclosing_class_id, import_map,
+            wildcard_packages, local_types, field_types, param_types, {},
+        )
+        if actual_type is None:
+            return None
+        raw = erased_type(actual_type).rsplit(".", 1)[-1]
+        generic_args = self._generic_type_arguments(actual_type)
+        if raw == "Optional" and len(generic_args) == 1:
+            return f"org.assertj.core.api.OptionalAssert<{generic_args[0]}>"
+        if raw in {
+            "Map", "HashMap", "LinkedHashMap", "TreeMap", "ConcurrentMap",
+        } and len(generic_args) == 2:
+            return f"org.assertj.core.api.MapAssert<{generic_args[0]},{generic_args[1]}>"
+        if raw in {
+            "List", "ArrayList", "LinkedList", "Set", "HashSet", "SortedSet",
+            "Collection", "Iterable",
+        } and len(generic_args) == 1:
+            return f"org.assertj.core.api.ListAssert<{generic_args[0]}>"
+        if raw and "." not in raw and raw not in _PRIMITIVE_TYPE_NAMES:
+            # A plain source/JDK object type: AssertJ's generic
+            # `assertThat(T actual)` overload returns `ObjectAssert<T>`.
+            return f"org.assertj.core.api.ObjectAssert<{actual_type}>"
+        return None
+
+    def _generic_return_type_from_source_method(
+        self, receiver_type: str, receiver_args: List[str], method_name: str,
+        call_node, source: bytes, module_name: str, import_map: Dict[str, str],
+        wildcard_packages: List[str], local_types: "_LocalScopes",
+        field_types: Dict[str, str], param_types: Dict[str, str],
+        enclosing_class_id: Optional[str] = None,
+        static_only: bool = False,
+    ) -> Optional[str]:
+        """Declared return type of the single source method a call selects
+        on `receiver_type` (own or inherited), or None when no unique
+        target exists. `static_only` restricts selection to `static`
+        members — used for a bare call walked up to a lexically enclosing
+        class from a *static* nested class, which has no enclosing instance
+        and can therefore only reach the outer class's static methods (JLS
+        8.1.3 / 15.12.1)."""
+        receiver_class_id = self._resolve_declared_type(
+            receiver_type, module_name, import_map, wildcard_packages,
+            enclosing_class_id,
+        )
+        if receiver_class_id is None:
+            return None
+        args_node = call_node.child_by_field_name("arguments")
+        arg_count = self._count_args(args_node)
+        arg_types = self._infer_arg_types(
+            args_node, source, local_types, param_types, field_types,
+        )
+        candidates = self._members_named(
+            receiver_class_id, method_name, search_ancestors=True,
+        )
+        # A unique zero-argument source method needs neither overload ranking
+        # nor argument/generic binding to choose its declared return.  Keep
+        # every non-zero-arg or ambiguous shape on the full resolver below.
+        direct_candidates = [
+            candidate for candidate in candidates
+            if self._arity_matches(candidate, 0)
+            and (not static_only or self._is_static_member(candidate))
+        ] if arg_count == 0 else []
+        if len(direct_candidates) == 1:
+            target_ids = direct_candidates
+        else:
+            arg_types = self._contextual_overload_arg_types(
+                candidates, arg_count, arg_types, args_node, source,
+                module_name, enclosing_class_id, import_map, wildcard_packages,
+                local_types, param_types, field_types, {},
+            )
+            target, _ = self._resolve_own_or_ancestor(
+                receiver_class_id, method_name, arg_count, arg_types,
+                0.9, 0.85, _ImportContext(
+                    module_name, import_map, wildcard_packages, enclosing_class_id,
+                ),
+                allow_method_type_inference=True,
+                narrowing_args=(args_node, source, local_types, param_types, field_types),
+                static_only=static_only,
+            )
+            target_ids = target if isinstance(target, list) else [target] if target else []
+        if len(target_ids) > 1:
+            # Varargs overload selection can conservatively retain several
+            # candidates even when every candidate is declared on the same
+            # class and has exactly the same return type.  Dispatch remains
+            # ambiguous, but the invocation's value type is not.  Reuse one
+            # representative only for return propagation; emitted call edges
+            # keep the existing fan-out/precision policy unchanged.
+            owners = {self._declaring_class_id(candidate) for candidate in target_ids}
+            returns = {
+                self.builder._nodes[candidate].metadata.get("java_return_type")
+                for candidate in target_ids
+                if candidate in self.builder._nodes
+            }
+            if len(owners) == 1 and None not in owners and len(returns) == 1 and None not in returns:
+                target_ids = [target_ids[0]]
+        if len(target_ids) != 1:
+            return None
+        target_node = self.builder._nodes.get(target_ids[0])
+        if target_node is None:
+            return None
+        return_type = target_node.metadata.get("java_return_type")
+        if not isinstance(return_type, str) or not return_type:
+            return None
+        declaring_class = self._declaring_class_id(target_ids[0]) or (
+            f"{target_node.module}:{target_node.contained_in}"
+            if target_node.contained_in else receiver_class_id
+        )
+        type_params = self._class_type_params.get(declaring_class, [])
+
+        # Most source methods return a concrete type (`String`, `Builder`,
+        # `void`, ...), so invocation argument binding and receiver generic
+        # substitution cannot affect their result.  The work below is needed
+        # only when the declared return actually mentions a method or class
+        # type variable.  Keep the conservative substring check deliberately
+        # one-sided: a false positive merely takes the old path; it can never
+        # skip a required substitution.
+        method_type_params = self._method_type_param_bounds.get(target_ids[0], {})
+        needs_method_binding = any(name in return_type for name in method_type_params)
+        needs_class_binding = any(name in return_type for name in type_params)
+        # Method type variables are inferred from invocation arguments, not
+        # from the receiver's class arguments.  For `<T> T proxy(T bean)`, a
+        # `SomeListener` argument makes the chained receiver type
+        # `SomeListener`; leaving it as bare `T` drops `proxy(bean).run()`.
+        # Keep this bounded to direct parameter variables with statically
+        # known argument types—nested constraints need a full JLS inference
+        # solver and must remain unresolved rather than guessed.
+        method_bindings: Dict[str, str] = {}
+        arg_nodes = argument_nodes(args_node) if needs_method_binding else []
+        # Erased argument types are unknown as a whole whenever any single
+        # argument is not statically knowable (`_infer_arg_types`), which is
+        # the common shape for `getOnlyElement(root.getChildren())`.  Keep
+        # the plain `T <- actual` binding gated on a known erased type, but
+        # let the structural bindings below (generic container arguments,
+        # generic arrays, class literals) inspect each argument node on its
+        # own so one unknown sibling argument does not drop every binding.
+        declared_params = self._param_type_lists.get(target_ids[0], [])
+        for index, declared in enumerate(declared_params) if needs_method_binding else ():
+            if arg_types is not None and index >= len(arg_types):
+                break
+            actual = arg_types[index] if arg_types is not None else None
+            parameter = erased_type(declared).strip()
+            if actual is not None and parameter in method_type_params:
+                method_bindings[parameter] = actual
+            # Bind a method variable nested in the same generic raw type:
+            # `<T> T exactlyOne(List<T> xs)` + `List<Filter>` -> Filter,
+            # including the common `Collection<? extends T>` form. The
+            # regular overload pass intentionally erases arguments, so
+            # recover the declared expression type here solely for return
+            # propagation. Require equal raw types and one-to-one generic
+            # arity; no subtype or wildcard-lower-bound guessing.
+            arg_node = arg_nodes[index] if index < len(arg_nodes) else None
+            raw_actual = (
+                self._infer_arg_type(
+                    arg_node, source, local_types, param_types, field_types,
+                )
+                if arg_node is not None else None
+            )
+            if raw_actual is None and arg_node is not None and arg_node.type == "method_invocation":
+                # A nested source call carries its declared generic return
+                # (`root.getChildren()` -> `Set<? extends Descriptor>`), so
+                # `<T> T getOnlyElement(Collection<T>)` binds `T` exactly the
+                # way a declared local of that type would.  The declared
+                # return is canonicalized by the declaring file's context, so
+                # the raw-type compatibility check below cannot be fooled by
+                # a same-simple-name project class at the call site.
+                raw_actual = self._generic_method_invocation_return_type(
+                    arg_node, source, module_name, enclosing_class_id, import_map,
+                    wildcard_packages, local_types, field_types, param_types, {},
+                )
+            declared_generic = self._generic_type_arguments(declared)
+            actual_generic = (
+                self._generic_type_arguments(raw_actual)
+                if isinstance(raw_actual, str) else []
+            )
+            if (
+                raw_actual is not None
+                and self._types_compatible(
+                    erased_type(declared).strip(), erased_type(raw_actual).strip(),
+                    self._param_ctx_for(target_ids[0]),
+                    _ImportContext(
+                        module_name, import_map, wildcard_packages, enclosing_class_id,
+                    ),
+                    allow_boxing=False,
+                )
+                and len(declared_generic) == len(actual_generic)
+            ):
+                for declared_arg, actual_arg in zip(declared_generic, actual_generic):
+                    variable = self._wildcard_upper_bound(declared_arg) or declared_arg
+                    if variable in method_type_params:
+                        method_bindings[variable] = (
+                            self._wildcard_upper_bound(actual_arg) or actual_arg
+                        )
+            # Preserve an element-type binding through generic array
+            # parameters.  For `<T> Stream<T> unique(T[] values)`, a
+            # `String[]` argument must make the chained receiver
+            # `Stream<String>`, otherwise downstream Stream method
+            # references lose their functional target type.  Require
+            # identical array rank and a reference component: a generic
+            # Java variable cannot stand for a primitive component.
+            dimensions = 0
+            component = parameter
+            while component.endswith("[]"):
+                dimensions += 1
+                component = component[:-2]
+            if dimensions and actual is not None and component in method_type_params:
+                actual_component = actual
+                for _ in range(dimensions):
+                    if not actual_component.endswith("[]"):
+                        actual_component = ""
+                        break
+                    actual_component = actual_component[:-2]
+                if actual_component and actual_component not in self._BOXED_PRIMITIVE:
+                    method_bindings[component] = actual_component
+            # `Class<E>` carries an exact binding at a class literal call
+            # site. Preserve that binding only when the variable is also
+            # present in this method's declared return type; this avoids
+            # treating an arbitrary generic parameter as a global type
+            # guess.
+            declared_args = self._generic_type_arguments(declared)
+            arg_node = arg_nodes[index] if index < len(arg_nodes) else None
+            variable = declared_args[0] if len(declared_args) == 1 else ""
+            if (
+                arg_node is not None and arg_node.type == "class_literal"
+                and variable and variable.isidentifier()
+                and re.search(rf"\b{re.escape(variable)}\b", return_type)
+            ):
+                literal = next((c for c in arg_node.children if c.is_named), None)
+                if literal is not None:
+                    method_bindings[variable] = self._text(literal, source)
+        # A generic fluent source method can receive its result binding from
+        # a method reference.  In `Events.<R>map(Function<? super Event,
+        # ? extends R>)`, `Event::getTestDescriptor` makes `R` exactly the
+        # getter's declared return.  Preserve only the unbound `Type::method`
+        # shape with one source-owned zero-argument candidate; overloaded,
+        # bound, and external references stay unresolved rather than guessed.
+        for index, declared in enumerate(self._param_type_lists.get(target_ids[0], [])) if needs_method_binding else ():
+            if index >= len(arg_nodes):
+                continue
+            declared_args = self._generic_type_arguments(declared)
+            if len(declared_args) < 2:
+                continue
+            variable = self._wildcard_upper_bound(declared_args[-1]) or declared_args[-1]
+            if (
+                not variable.isidentifier()
+                or variable not in method_type_params
+                or not re.search(rf"\b{re.escape(variable)}\b", return_type)
+            ):
+                continue
+            functional_arg = arg_nodes[index]
+            if functional_arg.type == "lambda_expression":
+                body = functional_arg.child_by_field_name("body")
+                if body is not None and body.type in {
+                    "method_invocation", "object_creation_expression",
+                }:
+                    inferred = self._declared_receiver_type_text(
+                        body, source, module_name, enclosing_class_id,
+                        import_map, wildcard_packages, local_types, field_types,
+                        param_types, {},
+                    )
+                    if inferred is not None:
+                        method_bindings[variable] = inferred
+                continue
+            if functional_arg.type != "method_reference":
+                continue
+            ref_node = functional_arg
+            named = [child for child in ref_node.children if child.is_named]
+            terminal = next(
+                (child for child in reversed(ref_node.children)
+                 if child.type in {"identifier", "new"}),
+                None,
+            )
+            if not named or terminal is None or terminal.type == "new":
+                continue
+            owner_id = self._resolve_declared_type(
+                self._text(named[0], source), module_name, import_map,
+                wildcard_packages, enclosing_class_id,
+            )
+            if owner_id is None:
+                continue
+            candidates = [
+                candidate for candidate in self._members_named(
+                    owner_id, self._text(terminal, source), search_ancestors=True,
+                )
+                if len(self._param_type_lists.get(candidate, [])) == 0
+            ]
+            returns = {
+                self.builder._nodes[candidate].metadata.get("java_return_type")
+                for candidate in candidates if candidate in self.builder._nodes
+            }
+            if len(candidates) == 1 and len(returns) == 1:
+                inferred = next(iter(returns))
+                if isinstance(inferred, str) and inferred and inferred != "void":
+                    method_bindings[variable] = inferred
+        if method_bindings:
+            return_type = self._replace_type_variables(return_type, method_bindings)
+            # A method binding can itself be a receiver-class variable (for
+            # example `<T> T identity(T value)` called with a `U` field on
+            # `Box<U>`).  Recheck after replacement so `U` is still
+            # substituted from the receiver rather than leaked as a
+            # declaration-site variable into the following chain.
+            needs_class_binding = needs_class_binding or any(
+                name in return_type for name in type_params
+            )
+        if needs_class_binding:
+            bindings = self._compose_type_var_bindings(
+                receiver_class_id, receiver_args, declaring_class,
+            )
+            resolved_args = [bindings.get(name, name) for name in type_params]
+            resolved_return = self._substitute_generic_return_type(
+                return_type, type_params, resolved_args,
+            )
+        else:
+            resolved_return = return_type
+        if resolved_return is None:
+            return None
+        # Within the declaring generic class, a raw receiver still knows the
+        # declaration-site upper bound: `class C<T extends Descriptor> { T
+        # get(); }` makes `get().id()` dispatch through `Descriptor`, not a
+        # fictional source class named `T`. Do not apply this to an actual
+        # receiver type argument, which was already substituted above.
+        raw_return = erased_type(resolved_return).strip()
+        if (
+            raw_return in type_params
+            and raw_return not in bindings
+            and (class_bound := self._class_type_param_bounds.get(declaring_class, {}).get(raw_return))
+        ):
+            resolved_return = class_bound
+        # A method inference variable that no argument bound is not a type
+        # named `T`.  JLS 18.1.3 resolves such a variable to its declared
+        # bound; an implicit `Object` bound carries no dispatch information
+        # and stays unknown, so a following `var` argument keeps the
+        # unknown-argument overload contract instead of failing every
+        # candidate against a phantom class `T`.
+        unbound = erased_type(resolved_return).strip()
+        unbound_rank = 0
+        while unbound.endswith("[]"):
+            unbound_rank += 1
+            unbound = unbound[:-2]
+        if unbound in method_type_params and unbound not in method_bindings:
+            bound = method_type_params[unbound].strip()
+            if not bound or erased_type(bound).strip() == "Object":
+                return None
+            resolved_return = bound + "[]" * unbound_rank
+        # A source method's return type is declared in the target method's
+        # compilation unit, not at the call site.  In particular, a simple
+        # member return type such as ``Builder`` on ``Option.builder()`` must
+        # mean ``Option.Builder`` even when the caller imports an unrelated
+        # ``HelpFormatter.Builder``.  Canonicalize it while the declaring
+        # method/file context is still available, then let the outer chain
+        # resolve that qualified text without caller-import aliasing.
+        declaring_ctx = self._file_ctx.get(target_node.file_path)
+        if declaring_ctx is not None:
+            # Preserve the declaration context of source-owned generic
+            # arguments as well as a directly returned source class.  A
+            # caller need not import ``Role`` merely because
+            # ``User.getRoles()`` is declared as ``Set<Role>`` in User.java.
+            # Qualifying that argument here lets a later JDK chain such as
+            # ``parallelStream()`` carry ``Stream<pkg.Role>`` into lambda
+            # inference without a global simple-name fallback.
+            generic_bindings: Dict[str, str] = {}
+            for generic_arg in self._generic_type_arguments(resolved_return):
+                bounded_arg = self._wildcard_upper_bound(generic_arg) or generic_arg
+                arg_class_id = self._resolve_declared_type(
+                    bounded_arg, declaring_ctx.module,
+                    declaring_ctx.import_map, declaring_ctx.wildcard_packages,
+                    declaring_class,
+                )
+                if arg_class_id is None or ":" not in arg_class_id:
+                    continue
+                arg_module, arg_qualname = arg_class_id.rsplit(":", 1)
+                generic_bindings[erased_type(bounded_arg).strip()] = (
+                    f"{self.builder._display_module(arg_module)}.{arg_qualname}"
+                )
+            resolved_return = self._replace_type_variables(
+                resolved_return, generic_bindings,
+            )
+            erased_return = erased_type(resolved_return).strip()
+            array_rank = 0
+            while erased_return.endswith("[]"):
+                array_rank += 1
+                erased_return = erased_return[:-2]
+            return_class_id = self._resolve_declared_type(
+                resolved_return, declaring_ctx.module,
+                declaring_ctx.import_map, declaring_ctx.wildcard_packages,
+                declaring_class,
+            )
+            if return_class_id is not None and ":" in return_class_id:
+                return_module, return_qualname = return_class_id.rsplit(":", 1)
+                # Keep the substituted generic arguments while qualifying
+                # the raw source return owner.  Dropping `<Event>` from
+                # `Result<Event>` here makes the next fluent hop see bare
+                # `Result`, so its SAM parameter `E` can never resolve.
+                return_args = self._generic_type_arguments(resolved_return)
+                generic_suffix = (
+                    "<" + ", ".join(return_args) + ">"
+                    if return_args else ""
+                )
+                return (
+                    f"{self.builder._display_module(return_module)}."
+                    f"{return_qualname}{generic_suffix}" + "[]" * array_rank
+                )
+            # The same provenance rule for a JDK raw owner: `Set` spelled in
+            # the declaring file means the exact class that file imports, so
+            # a caller that never imports `Set` can still check it against a
+            # `Collection<T>` parameter through the exact-FQN JDK facts.
+            # Only an explicit `java.` import qualifies; a bare or
+            # wildcard-imported name is left as written.
+            if return_class_id is None and "." not in erased_return:
+                imported_owner = declaring_ctx.import_map.get(erased_return)
+                if imported_owner is not None and imported_owner.startswith("java."):
+                    return_args = self._generic_type_arguments(resolved_return)
+                    generic_suffix = (
+                        "<" + ", ".join(return_args) + ">"
+                        if return_args else ""
+                    )
+                    return f"{imported_owner}{generic_suffix}" + "[]" * array_rank
+        return resolved_return
+
+    def _equivalent_type_texts(
+        self, left: str, right: str, module_name: str, import_map: Dict[str, str],
+        wildcard_packages: List[str], enclosing_class_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """Canonical spelling shared by two declared-type texts that name the
+        same type, or None.
+
+        Two spellings are one type when their raw owners resolve to the same
+        source class, or are one external name written bare in one place and
+        `java.`-qualified in the other (an exact JDK stub result versus a
+        declaring-file canonicalized return), and every generic argument is
+        pairwise equivalent by the same rule.  Array rank and wildcard shape
+        must agree.  Nothing else is unified: genuinely different types stay
+        unresolved rather than guessed.  The qualified spelling is preferred
+        so a following hop resolves it without caller imports."""
+        if left == right:
+            return left
+        left_bound = self._wildcard_upper_bound(left)
+        right_bound = self._wildcard_upper_bound(right)
+        if (left_bound is None) != (right_bound is None):
+            return None
+        if left_bound is not None:
+            inner = self._equivalent_type_texts(
+                left_bound, right_bound, module_name, import_map,
+                wildcard_packages, enclosing_class_id,
+            )
+            return f"? extends {inner}" if inner is not None else None
+        left_raw = erased_type(left).strip()
+        right_raw = erased_type(right).strip()
+        rank = 0
+        while left_raw.endswith("[]") and right_raw.endswith("[]"):
+            left_raw, right_raw, rank = left_raw[:-2], right_raw[:-2], rank + 1
+        if left_raw.endswith("[]") or right_raw.endswith("[]"):
+            return None
+        left_args = self._generic_type_arguments(left)
+        right_args = self._generic_type_arguments(right)
+        if len(left_args) != len(right_args):
+            return None
+        raw: Optional[str] = None
+        if left_raw == right_raw:
+            raw = left_raw
+        else:
+            left_id = self._resolve_declared_type(
+                left_raw, module_name, import_map, wildcard_packages, enclosing_class_id,
+            )
+            right_id = self._resolve_declared_type(
+                right_raw, module_name, import_map, wildcard_packages, enclosing_class_id,
+            )
+            if left_id is not None and left_id == right_id:
+                raw = left_raw if "." in left_raw else right_raw
+            elif left_id is None and right_id is None:
+                if left_raw.rsplit(".", 1)[-1] == right_raw.rsplit(".", 1)[-1]:
+                    qualified = [t for t in (left_raw, right_raw) if t.startswith("java.")]
+                    bare = [t for t in (left_raw, right_raw) if "." not in t]
+                    if qualified and bare:
+                        raw = qualified[0]
+        if raw is None:
+            return None
+        unified: List[str] = []
+        for left_arg, right_arg in zip(left_args, right_args):
+            same = self._equivalent_type_texts(
+                left_arg, right_arg, module_name, import_map,
+                wildcard_packages, enclosing_class_id,
+            )
+            if same is None:
+                return None
+            unified.append(same)
+        suffix = "<" + ", ".join(unified) + ">" if unified else ""
+        return raw + suffix + "[]" * rank
+
+    def _compose_type_var_bindings(
+        self, receiver_class_id: str, receiver_args: List[str], declaring_class: str,
+    ) -> Dict[str, str]:
+        """Type-variable bindings valid at `declaring_class`'s own scope,
+        given the receiver's declared type arguments at the call site.
+
+        `receiver_args` only binds `receiver_class_id`'s *own* type
+        parameters (`Box<Stripe> box` -> `T := Stripe` on `Box` itself). When
+        the method is declared on an ancestor (`StripeBox extends
+        Box<Stripe>`, receiver typed as bare `StripeBox`), that binding isn't
+        on the receiver at all — it's on the inheritance edge. This walks the
+        INHERITS/IMPLEMENTS path from `receiver_class_id` to `declaring_class`
+        (`_ancestor_path`) and composes `_ancestor_type_args` at each hop,
+        substituting the previous hop's bindings into each edge's argument
+        text before binding the next hop's own type parameters — so a
+        multi-level chain (`Sub<X> extends Mid<X>`, `Mid<T> extends Box<T>`)
+        or an interface hierarchy resolves the same way a class chain does."""
+        own_params = self._class_type_params.get(receiver_class_id, [])
+        bindings = {
+            name: receiver_args[idx]
+            for idx, name in enumerate(own_params)
+            if idx < len(receiver_args)
+        }
+        if receiver_class_id == declaring_class:
+            return bindings
+        path = self._ancestor_path(receiver_class_id, declaring_class)
+        if path is None:
+            return {}
+        cur = receiver_class_id
+        for nxt in path:
+            edge_args = self._ancestor_type_args.get((cur, nxt), [])
+            substituted = [
+                self._replace_type_variables(arg, bindings) for arg in edge_args
+            ]
+            next_params = self._class_type_params.get(nxt, [])
+            bindings = {
+                name: substituted[idx]
+                for idx, name in enumerate(next_params)
+                if idx < len(substituted)
+            }
+            cur = nxt
+        return bindings
+
+    def _ancestor_path(self, start: str, target: str) -> Optional[List[str]]:
+        """BFS over INHERITS ∪ IMPLEMENTS from `start` to `target`, returning
+        the chain of class ids from `start`'s first hop through `target`
+        (nearest ancestor first, mirroring `_class_ancestors`'s own
+        traversal order). `[]` if `start == target`; `None` if unreachable."""
+        if start == target:
+            return []
+        seen: Set[str] = {start}
+        q: deque = deque(
+            (anc, [anc]) for anc in (
+                self._direct_ancestors(start, EdgeType.INHERITS)
+                + self._direct_ancestors(start, EdgeType.IMPLEMENTS)
+            )
+        )
+        while q:
+            cur, path = q.popleft()
+            if cur == target:
+                return path
+            if cur in seen:
+                continue
+            seen.add(cur)
+            for nxt in (
+                self._direct_ancestors(cur, EdgeType.INHERITS)
+                + self._direct_ancestors(cur, EdgeType.IMPLEMENTS)
+            ):
+                q.append((nxt, path + [nxt]))
+        return None
+
+    def _substitute_generic_return_type(
+        self, return_type: str, type_params: List[str], receiver_args: List[str],
+    ) -> Optional[str]:
+        if not type_params or not receiver_args:
+            return self._wildcard_upper_bound(return_type) or return_type
+        bindings = {
+            name: receiver_args[idx]
+            for idx, name in enumerate(type_params)
+            if idx < len(receiver_args)
+        }
+        substituted = self._replace_type_variables(return_type, bindings)
+        return self._wildcard_upper_bound(substituted) or substituted
+
+    @classmethod
+    def _replace_type_variables(cls, type_text: str, bindings: Dict[str, str]) -> str:
+        if not bindings:
+            return type_text
+        out: List[str] = []
+        idx = 0
+        while idx < len(type_text):
+            ch = type_text[idx]
+            if ch.isalpha() or ch in "_$":
+                start = idx
+                idx += 1
+                while idx < len(type_text) and (
+                    type_text[idx].isalnum() or type_text[idx] in "_$"
+                ):
+                    idx += 1
+                ident = type_text[start:idx]
+                out.append(bindings.get(ident, ident))
+                continue
+            out.append(ch)
+            idx += 1
+        return "".join(out)
+
+    @staticmethod
+    def _generic_type_arguments(type_text: str) -> List[str]:
+        start = type_text.find("<")
+        if start < 0:
+            return []
+        depth = 0
+        end = -1
+        for idx in range(start, len(type_text)):
+            ch = type_text[idx]
+            if ch == "<":
+                depth += 1
+            elif ch == ">":
+                depth -= 1
+                if depth == 0:
+                    end = idx
+                    break
+        if end < 0:
+            return []
+        args: List[str] = []
+        part_start = start + 1
+        depth = 0
+        for idx in range(start + 1, end):
+            ch = type_text[idx]
+            if ch == "<":
+                depth += 1
+            elif ch == ">":
+                depth -= 1
+            elif ch == "," and depth == 0:
+                arg = type_text[part_start:idx].strip()
+                if arg:
+                    args.append(arg)
+                part_start = idx + 1
+        last = type_text[part_start:end].strip()
+        if last:
+            args.append(last)
+        return args
+
+    @staticmethod
+    def _wildcard_upper_bound(type_text: str) -> Optional[str]:
+        match = re.match(r"^\?\s+extends\s+(.+)$", type_text.strip())
+        return match.group(1).strip() if match else None