rigortype 0.1.18 → 0.1.19

data/lib/rigor/inference/expression_typer.rb

@@ -6,6 +6,7 @@ require_relative "../type"
 require_relative "../ast"
 require_relative "../analysis/self_call_resolution_recorder"
 require_relative "block_parameter_binder"
+require_relative "body_fixpoint"
 require_relative "budget_trace"
 require_relative "fallback"
 require_relative "flow_tracer"
@@ -199,7 +200,11 @@ module Rigor
         Prism::ForwardingArgumentsNode => :type_of_non_value,
         Prism::WhileNode => :type_of_loop,
         Prism::UntilNode => :type_of_loop,
-        Prism::ForNode => :type_of_dynamic_top,
+        # `for` matches `eval_for`'s statement-path policy: the loop
+        # expression types `Constant[nil]` (no `break VALUE` observed),
+        # same as `while` / `until` — annotating a `for`'s `end` line as
+        # `Dynamic[top]` was a display artifact of the old mapping.
+        Prism::ForNode => :type_of_loop,
         Prism::DefinedNode => :type_of_defined,
         Prism::NumberedReferenceReadNode => :type_of_numbered_reference,
         Prism::BackReferenceReadNode => :type_of_back_reference,
@@ -708,7 +713,21 @@ module Rigor
         polarity = constant_value_polarity(left_type)
         return short_circuit_for(node, left_type, polarity) if polarity
 
-        Type::Combinator.union(left_type, type_of(node.right))
+        # The left operand only flows through on the edge that short-
+        # circuits: `a || b` yields `a` solely when `a` is truthy, so its
+        # falsey constituents (`nil` / `false`) can never be the value of
+        # the OrNode (they hand off to `b`); `a && b` yields `a` solely
+        # when `a` is falsey. Narrow the surviving left edge before the
+        # union so `s || full` (with `s : String?`) types `String |
+        # <full>` rather than re-admitting the stripped `nil`. Mirrors
+        # `StatementEvaluator#eval_and_or`'s `skipped_type`.
+        surviving_left =
+          if node.is_a?(Prism::AndNode)
+            Narrowing.narrow_falsey(left_type)
+          else
+            Narrowing.narrow_truthy(left_type)
+          end
+        Type::Combinator.union(surviving_left, type_of(node.right))
       end
 
       def short_circuit_for(node, left_type, polarity)
@@ -969,11 +988,26 @@ module Rigor
         Type::Combinator.nominal_of(Regexp)
       end
 
+      # A range endpoint folds to a static value when it is a literal
+      # (`IntegerNode` / `StringNode`) or when its *evaluated* type is a
+      # `Constant<v>` carrying a range-able value (Integer / Float /
+      # String — matching the literal-path value kinds). The evaluated
+      # arm lets `(1..n)` fold to `Constant<Range>` when per-call body
+      # inference has pinned `n` to a constant (fact2 chain). A `nil`
+      # node is a beginless/endless boundary: keep today's static-nil
+      # behaviour (which yields `Constant<Range>` only when the *other*
+      # end is also static, preserving today's beginless/endless path).
       def static_range_endpoint(node)
         return [true, nil] if node.nil?
         return [true, node.value] if node.is_a?(Prism::IntegerNode)
         return [true, node.unescaped] if node.is_a?(Prism::StringNode) && node.respond_to?(:unescaped)
 
+        type = type_of(node)
+        if type.is_a?(Type::Constant)
+          value = type.value
+          return [true, value] if value.is_a?(Integer) || value.is_a?(Float) || value.is_a?(String)
+        end
+
         [false, nil]
       end
 
@@ -1166,14 +1200,12 @@ module Rigor
         return nil unless local_def
 
         local_inference = infer_top_level_user_method(local_def, receiver, arg_types)
-        return local_inference if local_inference && adoptable_self_call_result?(local_inference)
+        return local_inference if local_inference
 
         # The local def matches by name but the inference was
-        # disqualified — either the parameter shape is too complex
-        # for the first-iteration binder (kwargs / optionals /
-        # rest), or ADR-24 slice 1's conservative gate declined
-        # the resolved return type inside a class body (see
-        # `adoptable_self_call_result?`). `Dynamic[Top]` is the
+        # disqualified — the parameter shape is too complex for the
+        # first-iteration binder (kwargs / optionals / rest), so the
+        # body could not be re-typed. `Dynamic[Top]` is the
         # safest answer: RBS dispatch would be wrong (the method
         # is user-defined and shadows whatever ancestor method the
         # dispatch would find), and `Dynamic[Top]` propagates
@@ -1211,6 +1243,9 @@ module Rigor
         per_element = try_per_element_block_fold(node, receiver)
         return per_element if per_element
 
+        inject_fold = try_block_inject_fold(node, receiver, arg_types)
+        return inject_fold if inject_fold
+
         hash_transform = try_hash_shape_block_fold(node, receiver)
         return hash_transform if hash_transform
 
@@ -1231,11 +1266,17 @@ module Rigor
         # the body with the call's argument types bound and
         # return the body's last-expression type.
         user_inference = try_user_method_inference(receiver, node, arg_types)
-        if user_inference
-          return user_inference if adoptable_self_call_result?(user_inference)
-
-          return dynamic_top
-        end
+        return user_inference if user_inference
+
+        # Module-singleton call resolution (ADR-57 follow-up) — when the
+        # receiver is `Singleton[Foo]` (a module/class constant or a
+        # singleton-method `self`) and `Foo` declares a user-side
+        # `def self.x` / `module_function` body, re-type that body
+        # with the call args bound. Sits after the RBS dispatch tier, so
+        # foreign / RBS-known singletons (`Math.sqrt`) keep their catalog
+        # answer; only project-defined singleton methods reach here.
+        singleton_inference = try_singleton_method_inference(receiver, node, arg_types)
+        return singleton_inference if singleton_inference
 
         # Dynamic-origin propagation: when the receiver is Dynamic[T] and
         # no positive rule resolves the call, the result inherits the
@@ -1341,34 +1382,102 @@ module Rigor
       # definitions and the file's top-level defs. Before
       # slice 1 every such call typed `Dynamic[top]`.
       #
-      # The adoption of the resolved return type is gated:
+      # The resolved return type is adopted UNCONDITIONALLY — a resolved
+      # user-method call site reads the callee's inferred return, exactly as a
+      # toplevel call has since v0.0.3.
       #
-      # - At top-level / inside a DSL block (`scope.self_type`
-      #   is nil) the result is adopted unchanged — this is
-      #   the pre-slice-1 surface (the v0.0.3 A local-`def`
-      #   shortcut) and MUST keep working.
-      # - Inside a class body / method body (`self_type` set)
-      #   the result is adopted ONLY when it is `Bot`. A `Bot`
-      #   return is an always-diverging guard helper; adopting
-      #   it can only ever enable correct terminating-branch
-      #   narrowing, never a new `undefined-method` /
-      #   argument-type false positive. A non-`Bot` resolved
-      #   return is kept as `Dynamic[top]` (WD3) — adopting
-      #   precise non-`Bot` returns project-wide awaits the
-      #   callee-return-inference precision a later slice
-      #   brings (measured: unconditional adoption regressed
-      #   `rigor check lib` by 16 diagnostics).
-      def adoptable_self_call_result?(type)
-        scope.self_type.nil? || type.is_a?(Type::Bot)
+      # ADR-24 WD3 originally gated this: inside a class / method body only a
+      # `Bot` return was adopted, everything else stayed `Dynamic[top]`, because
+      # an early unconditional-adoption experiment regressed `rigor check lib`
+      # by 16 diagnostics. ADR-55 / ADR-56 then chipped the gate open for the
+      # recursive-fixpoint summary and the value-pinned unroll envelope. ADR-57
+      # closed the arc: it re-ran the gate-open experiment per engine generation
+      # and adjudicated every firing as genuine-or-artifact, fixing the
+      # artifacts at their root — the tail-only body evaluator dropping explicit
+      # `return` (slice 1), multi-value returns not contributing a Tuple
+      # (slice 1), escaping block-captured content mutation surviving as a
+      # precise seed both inline and across a method boundary (slices 2/3), two
+      # over-strict self-authored RBS signatures (slice 1), and an over-optional
+      # tuple-slot destructure (slice 3). With the residual all genuine-or-win,
+      # the gate opened permanently on 2026-06-12 (ADR-57 WD2): the gate-open
+      # `rigor check lib` + plugin self-check delta is zero, and the Mastodon /
+      # haml / kramdown corpora show only adjudicated wins (a more precise error
+      # message; FP removals).
+      #
+      # The historical `adoptable_self_call_result?` predicate (its
+      # `self_type.nil?` / `Bot` / fixpoint-summary / unroll special cases) is
+      # now subsumed by unconditional adoption and removed; `try_local_def_
+      # dispatch` / `try_user_method_inference` simply return the inferred
+      # return. `clamp_unroll_result` still backstops an untrustworthy unrolled
+      # value independently of adoption.
+
+      # An extended (value-keyed) guard frame is `[plain_signature,
+      # value_key]` where `plain_signature` is itself the `[receiver,
+      # method]` pair; a plain frame is that pair directly.
+      def extended_frame?(frame)
+        frame.is_a?(Array) && frame.size == 2 && frame.first.is_a?(Array)
+      end
+
+      # The plain `(receiver, method)` signature carried by a guard frame:
+      # the frame itself for a plain frame, or its first element for an
+      # extended (value-keyed) frame.
+      def plain_part(frame)
+        extended_frame?(frame) ? frame.first : frame
+      end
+
+      # True when `type` is a concrete value — a `Type::Constant` or a
+      # `Type::Tuple` whose elements are (recursively) all value-pinned.
+      # ADR-55 slice 1: a value-pinned self-call result is adopted even
+      # inside a class/method body (where WD3 otherwise keeps non-`Bot`
+      # returns as `Dynamic[top]`). A concrete value at a call site is
+      # strictly more precise and can never enable an undefined-method or
+      # argument-type false positive — it is FP-neutral by construction.
+      def fully_value_pinned?(type)
+        case type
+        when Type::Constant then true
+        when Type::Tuple then type.elements.all? { |element| fully_value_pinned?(element) }
+        else false
+        end
       end
 
       def try_user_method_inference(receiver, call_node, arg_types)
         return nil unless receiver.is_a?(Type::Nominal)
 
-        def_node = resolve_user_def_through_ancestors(receiver.class_name, call_node.name)
+        def_node, owner = resolve_user_def_with_owner(receiver.class_name, call_node.name)
         return nil if def_node.nil?
 
-        infer_user_method_return(def_node, receiver, arg_types)
+        result = infer_user_method_return(def_node, receiver, arg_types)
+        return result if result.nil?
+
+        degrade_if_overridable(result, owner, call_node.name, :instance)
+      rescue StandardError
+        nil
+      end
+
+      # Module-singleton call resolution (ADR-57 follow-up) — resolves
+      # `Foo.<name>` on a `Singleton[Foo]` receiver against `Foo`'s
+      # user-side singleton defs (`def self.x`, `def Foo.x`, a
+      # `class << self` body, or a `module_function` method) and re-types
+      # the body with the call's argument types bound. The body scope's
+      # `self_type` is the SAME `Singleton[Foo]` carrier, so an
+      # implicit-self call inside (`def self.via; helper(x); end`)
+      # re-enters this tier and resolves against the same singleton table
+      # — the symmetric counterpart of the instance-side ancestor walk.
+      #
+      # Resolution is OWN-class only: the singleton-ancestry chain
+      # (`extend`ed modules, inherited class-method dispatch) is not
+      # walked at this slice. A miss degrades to today's `Dynamic[top]`,
+      # never a false resolution (ADR-57 follow-up § module-singleton).
+      def try_singleton_method_inference(receiver, call_node, arg_types)
+        return nil unless receiver.is_a?(Type::Singleton)
+
+        def_node = scope.singleton_def_for(receiver.class_name, call_node.name)
+        return nil if def_node.nil?
+
+        result = infer_user_method_return(def_node, receiver, arg_types)
+        return result if result.nil?
+
+        degrade_if_overridable(result, receiver.class_name, call_node.name, :singleton)
       rescue StandardError
         nil
       end
@@ -1417,15 +1526,27 @@ module Rigor
       end
 
       def resolve_user_def_through_ancestors(class_name, method_name)
+        resolve_user_def_with_owner(class_name, method_name).first
+      end
+
+      # ADR-57 N5 follow-up — resolves the method's def node AND the
+      # ancestor that owns it (the class/module whose own `def` table
+      # holds the body, which may differ from `class_name` when the
+      # method is inherited from a superclass or included module). The
+      # owner is what the overridable-method adoption gate keys on. Both
+      # are cached together (the walk is identical to the def-only path it
+      # replaced) and returned as a `[def_node, owner]` pair; `owner` is
+      # nil exactly when `def_node` is nil.
+      def resolve_user_def_with_owner(class_name, method_name)
         cache = class_graph_buckets[:user_def]
         table = (cache[class_name.to_s] ||= {})
         key = method_name.to_sym
         return table[key] if table.key?(key)
 
-        table[key] = compute_user_def_through_ancestors(class_name, method_name)
+        table[key] = compute_user_def_with_owner(class_name, method_name)
       end
 
-      def compute_user_def_through_ancestors(class_name, method_name)
+      def compute_user_def_with_owner(class_name, method_name)
         queue = [class_name.to_s]
         seen = {}
         visited = 0
@@ -1437,15 +1558,15 @@ module Rigor
           visited += 1
           if visited > ANCESTOR_WALK_LIMIT
             BudgetTrace.hit(BudgetTrace::ANCESTOR_WALK_LIMIT)
-            return nil
+            return [nil, nil]
           end
 
           found = scope.user_def_for(current, method_name)
-          return found if found
+          return [found, current] if found
 
           enqueue_ancestors(current, queue)
         end
-        nil
+        [nil, nil]
       end
 
       # Pushes `current`'s direct ancestors onto the BFS queue:
@@ -1496,10 +1617,260 @@ module Rigor
           scope.discovered_includes.key?(name)
       end
 
+      # ADR-57 N5 — overridable-method adoption gate. A self-call resolved
+      # to a project `def` whose owner has a discovered subclass / includer
+      # that REDEFINES the same method (same instance-vs-singleton kind) is
+      # a template-method site: the base body's literal return is the
+      # *default*, not the value every receiver sees, so adopting it as a
+      # flow constant is unsound (rgl `module Graph; def directed?; false`
+      # folds `unless directed?` always-true, ignoring `DirectedAdjacencyGraph`
+      # overriding it to `true` — the entire rgl warning set, per the
+      # 2026-06-13 app/network survey N5 row). On such a hit the precise
+      # return degrades to `Dynamic[top]`, deliberately re-opening a Dynamic
+      # source ONLY for genuinely-overridden methods. A method with no
+      # discovered override folds exactly as before — over-conservatism must
+      # not re-open Dynamic for final methods.
+      #
+      # The gate only inspects a *flow-constant-foldable* result (a
+      # `Constant`, or a `Tuple` of such): only a value-pinned return can
+      # mislead a downstream `if`/`unless`/`case` into an
+      # `always-truthy-condition` fold, which is exactly the unsoundness the
+      # gate exists to remove. A `Nominal` / `Dynamic` / union return cannot
+      # produce a flow constant, so adopting it from an overridden method is
+      # harmless and is left untouched — this keeps the override-relation
+      # walk off the hot path for the overwhelming majority of self-calls
+      # (whose return is not a bare constant).
+      def degrade_if_overridable(result, owner, method_name, kind)
+        return result if owner.nil?
+        return result unless fully_value_pinned?(result)
+        return result unless overridden_in_project?(owner.to_s, method_name, kind)
+
+        dynamic_top
+      end
+
+      OVERRIDE_GATE_CACHE_KEY = :__rigor_overridable_method_gate__
+      private_constant :OVERRIDE_GATE_CACHE_KEY
+
+      # Run-scoped memo for {#overridden_in_project?}, keyed (like
+      # `class_graph_buckets`) by the identity of the frozen discovery
+      # trio so a new analysis generation lands in a fresh bucket, then
+      # nested `kind → owner → method_name`. The predicate is a pure
+      # function of those tables. Nesting avoids allocating a composite
+      # cache key on the hot path (the gate runs on every adopted self-call
+      # return), so a steady-state hit is three identity hash reads + two
+      # string/symbol hash reads with zero allocation.
+      def override_gate_buckets
+        store = (Thread.current[OVERRIDE_GATE_CACHE_KEY] ||= {}.compare_by_identity)
+        by_def = (store[scope.discovered_def_nodes] ||= {}.compare_by_identity)
+        by_super = (by_def[scope.discovered_superclasses] ||= {}.compare_by_identity)
+        by_super[scope.discovered_includes] ||= { instance: {}, singleton: {} }
+      end
+
+      # True when some discovered project class/module — distinct from
+      # `owner` — redefines `(method_name, kind)` AND is related to `owner`
+      # (a transitive discovered subclass of an owner class, or a
+      # class/module that includes/prepends — extends, for singleton kind —
+      # an owner module). A same-name reopen of `owner` itself is NOT an
+      # override (monkey-patch reopen shares the owner identity). Memoized
+      # per `(owner, method_name, kind)`.
+      def overridden_in_project?(owner, method_name, kind)
+        by_owner = (override_gate_buckets[kind][owner] ||= {})
+        return by_owner[method_name] if by_owner.key?(method_name)
+
+        by_owner[method_name] = compute_overridden_in_project?(owner, method_name, kind)
+      end
+
+      def compute_overridden_in_project?(owner, method_name, kind)
+        redefiners_of(method_name, kind).any? do |candidate|
+          next false if candidate == owner
+
+          related_to_owner?(candidate, owner)
+        end
+      end
+
+      # Every discovered project class/module whose OWN def table redefines
+      # `(method_name, kind)`. Instance kind reads `discovered_def_nodes`,
+      # singleton kind reads `discovered_singleton_def_nodes` — both are
+      # genuine project `def` bodies (not RBS / accessor synthesis), so a
+      # name's presence is a real redefinition. Served from a per-generation
+      # inverted index (`method_name → [owner names]`) built once per def
+      # table, so the lookup is a single hash read rather than a full-table
+      # scan on every `(method_name, kind)` first-miss — the gate runs on
+      # every adopted self-call return, so the full-table `filter_map` it
+      # replaced was the dominant added allocation on a large `lib`.
+      def redefiners_of(method_name, kind)
+        method_definers_index(kind)[method_name] || EMPTY_REDEFINERS
+      end
+
+      EMPTY_REDEFINERS = [].freeze
+      private_constant :EMPTY_REDEFINERS
+
+      METHOD_DEFINERS_INDEX_KEY = :__rigor_method_definers_index__
+      private_constant :METHOD_DEFINERS_INDEX_KEY
+
+      # Per-generation `method_name (Symbol) → [owner names]` inverted index
+      # over the instance / singleton def tables, memoised by the identity
+      # of the def table it inverts (a new analysis generation lands in a
+      # fresh bucket). The toplevel sentinel is excluded — a toplevel `def`
+      # has no class ancestry and so can never be an override.
+      def method_definers_index(kind)
+        table = kind == :singleton ? scope.discovered_singleton_def_nodes : scope.discovered_def_nodes
+        store = (Thread.current[METHOD_DEFINERS_INDEX_KEY] ||= {}.compare_by_identity)
+        store[table] ||= build_method_definers_index(table)
+      end
+
+      def build_method_definers_index(table)
+        index = {}
+        table.each do |class_name, methods|
+          next if class_name == Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
+
+          methods.each_key { |method_name| (index[method_name] ||= []) << class_name }
+        end
+        index
+      end
+
+      # True when `candidate`'s transitive ancestor chain (superclasses +
+      # included/prepended modules) reaches `owner` — i.e. `candidate` is a
+      # subclass of an owner class or an includer of an owner module. Reuses
+      # the same BFS resolver the method-resolution ancestor walk uses, so
+      # name resolution (lexical nesting, RBS-known-ancestor pruning) is
+      # identical.
+      def related_to_owner?(candidate, owner)
+        queue = []
+        enqueue_ancestors(candidate, queue)
+        seen = {}
+        visited = 0
+        until queue.empty?
+          current = queue.shift
+          next if current.nil? || seen[current]
+
+          return true if current == owner
+
+          seen[current] = true
+          visited += 1
+          return false if visited > ANCESTOR_WALK_LIMIT
+
+          enqueue_ancestors(current, queue)
+        end
+        false
+      end
+
       INFERENCE_GUARD_KEY = :__rigor_user_method_inference_stack__
       private_constant :INFERENCE_GUARD_KEY
 
-      def infer_user_method_return(def_node, receiver, arg_types)
+      INFERENCE_UNROLL_FUEL_KEY = :__rigor_user_method_unroll_fuel__
+      private_constant :INFERENCE_UNROLL_FUEL_KEY
+
+      # ADR-55 slice 2 — thread-local fixpoint return-summary table,
+      # keyed by the plain `(receiver, method)` signature (NOT the
+      # value-extended signature: extended frames from slice 1 share the
+      # same summary). Each entry is `{ assumption:, consulted: }` where
+      # `assumption` is the current Kleene iterate (seeded `bot`) and
+      # `consulted` flips true when an in-cycle re-entry returns it.
+      INFERENCE_SUMMARY_KEY = :__rigor_user_method_return_summary__
+      private_constant :INFERENCE_SUMMARY_KEY
+
+      # Monotonic per-thread counter, bumped once each time `consult_summary`
+      # actually reads an in-flight fixpoint assumption (ADR-55 slice 2). A
+      # method return computed across an interval in which this counter does
+      # NOT move depended on no transient Kleene iterate, so it is FINAL and
+      # safe to memoise — even when the `summaries` table is non-empty because
+      # some unrelated outermost frame merely *seeded* (but never consulted)
+      # its own entry. See `infer_user_method_return`'s post-hoc memo gate.
+      SUMMARY_CONSULT_COUNTER_KEY = :__rigor_user_method_summary_consults__
+      private_constant :SUMMARY_CONSULT_COUNTER_KEY
+
+      # Per-thread append-only log of the seed depths of every in-flight
+      # summary `consult_summary` read (ADR-55 slice 2 mutual-recursion
+      # soundness fix, 2026-06-12). Each fixpoint owner records the guard
+      # stack size at seed time on its entry (`depth:`); a consult appends
+      # the consulted entry's depth here. A fixpoint whose body evaluation
+      # logged a depth SHALLOWER than its own seed depth read an ancestor
+      # signature's transient Kleene iterate -- cross-signature mutual
+      # recursion (`even?`/`odd?`) -- so its computed return is entangled
+      # with a not-yet-converged foreign assumption and must degrade to
+      # `untyped` rather than fold one branch's seed into a "final"
+      # constant. Own-signature consults log depth == own depth, and a
+      # nested fixpoint that completes within the evaluation logs depths
+      # > own depth; neither is foreign. Cleared with the summary table
+      # when the guard stack drains to empty.
+      SUMMARY_CONSULT_DEPTHS_KEY = :__rigor_user_method_summary_consult_depths__
+      private_constant :SUMMARY_CONSULT_DEPTHS_KEY
+
+      # ADR-57 follow-up — run-scoped memo for resolved user-method
+      # return types. The ADR-57 gate-open made every resolved in-body
+      # self-call adopt the callee's inferred return, which re-types the
+      # callee body once per call site. With a project-wide discovery
+      # index, file N re-types callees defined in files 1..N-1, so
+      # whole-`lib` cost grows superlinearly in files-per-process (the
+      # 2026-06-12 Rails survey's whole-`lib` scaling wall).
+      #
+      # `infer_user_method_return` is a pure function of
+      # `(def_node, receiver, arg_types)` PLUS the frozen project
+      # discovery index: `build_user_method_body_scope` binds the args
+      # to the params in a FRESH `Scope` seeded from an empty fact /
+      # narrowing store and inherits `scope.discovery` whole by
+      # reference — the caller's narrowing state never enters. (This is
+      # what makes a signature-keyed return memo sound where the
+      # ADR-52 WD5 per-call-NODE contribution cache was not: that cache
+      # keyed scope-sensitive results on the node; this memo keys a
+      # scope-INSENSITIVE result on its real inputs.)
+      #
+      # Two dimensions are call-site-varying and so live IN the key:
+      # the receiver carrier (`describe(:short)`) and the argument-type
+      # signature (`describe(:short)` of each arg) — value-pinned args
+      # change folds (`factorial(5)` vs `factorial(6)`), so a coarser
+      # key would serve a stale fold. The third unsafe dimension —
+      # the ADR-55 recursion machinery (unroll fuel / fixpoint Kleene
+      # assumption / WD1 clamp) producing a TRANSIENT result rather
+      # than a final return — is excluded structurally: the memo is
+      # consulted and populated ONLY when the incoming guard stack is
+      # empty (a genuine top-of-stack entry, whose result is final and
+      # cannot be an in-progress assumption or a clamped value). Frames
+      # entered with a non-empty stack bypass the memo entirely and
+      # compute as before.
+      #
+      # Keyed by the identity of the frozen discovery `def_nodes`
+      # table (a new analysis generation lands in a fresh bucket,
+      # mirroring `class_graph_buckets`) then by the identity of the
+      # `def_node` and the `[receiver, *args]` descriptor tuple.
+      # `ExpressionTyper` is rebuilt per `Scope#type_of`, so the store
+      # lives on `Thread.current`; fork-pool workers are separate
+      # processes, so it never crosses a project boundary.
+      RETURN_MEMO_KEY = :__rigor_user_method_return_memo__
+      private_constant :RETURN_MEMO_KEY
+
+      # Per-inference recursion context threaded through the guard /
+      # fixpoint helpers (ADR-55 slice 2). Bundles the call descriptor
+      # (`receiver`, `arg_types`, `plain_signature`), the thread-local
+      # summary table, and the WD1 clamp flag so the helpers stay within the
+      # parameter-list budget. `def_node` is carried separately (it is the
+      # body owner, not call context).
+      RecursionContext = Data.define(
+        :receiver, :arg_types, :plain_signature, :summaries, :would_have_been_guarded
+      )
+      private_constant :RecursionContext
+
+      # Total body evaluations the fixpoint iteration is permitted per
+      # outermost entry for a signature (ADR-55 WD2). Hard, non-configurable
+      # — the iteration cap is part of the termination story (ADR-41 WD4).
+      RECURSION_FIXPOINT_CAP = 3
+      private_constant :RECURSION_FIXPOINT_CAP
+
+      # Hard, non-configurable caps for the ADR-55 slice 1 constant-arg
+      # unroll. `RECURSION_UNROLL_FUEL` bounds the number of extended
+      # (value-keyed) frames per outermost inference entry;
+      # `RECURSION_VALUE_SIZE_CAP` disqualifies a frame whose pinned
+      # argument values are structurally large. Both are termination
+      # guards (ADR-41 WD4) — not measurement-gated precision budgets —
+      # so they ship default-on with no opt-in.
+      RECURSION_UNROLL_FUEL = 32
+      private_constant :RECURSION_UNROLL_FUEL
+
+      RECURSION_VALUE_SIZE_CAP = 64
+      private_constant :RECURSION_VALUE_SIZE_CAP
+
+      def infer_user_method_return(def_node, receiver, arg_types) # rubocop:disable Metrics/AbcSize
         return nil if def_node.body.nil?
 
         body_scope = build_user_method_body_scope(def_node, receiver, arg_types)
@@ -1518,19 +1889,463 @@ module Rigor
         # resolving during the main walk. `describe(:short)`
         # keeps non-Nominal receivers (the implicit `Object`
         # carrier for top-level / DSL-block defs) printable.
-        signature = [receiver.describe(:short), def_node.name]
+        plain_signature = [receiver.describe(:short), def_node.name]
         stack = (Thread.current[INFERENCE_GUARD_KEY] ||= [])
+        summaries = (Thread.current[INFERENCE_SUMMARY_KEY] ||= {})
+
+        # ADR-57 follow-up — return memo. The inferred return is a pure
+        # function of `(def_node, receiver, arg_types)` and the frozen
+        # discovery index whenever the computation does NOT depend on a
+        # transient ADR-55 Kleene assumption (an in-flight fixpoint summary).
+        # Two structural preconditions decide whether THIS frame's result is
+        # even a memo candidate, both stable across the body walk: the
+        # signature must not already be on the recursion guard stack (else we
+        # are inside its own cycle) and no constant-arg unroll may be in
+        # flight (its value-keyed frames are transient). When both hold we
+        # consult the memo, and on a miss we compute, then store the result
+        # only if no fixpoint summary was *consulted* during the computation
+        # (the post-hoc consult-counter check) — which is sound regardless of
+        # whether the `summaries` table holds inert *seeded-but-unconsulted*
+        # entries left by unrelated outermost frames. This is the fix for the
+        # whole-`lib` scaling wall: a deep DAG of non-recursive private
+        # readers (ActiveStorage `video_analyzer.rb`) seeded a summary on its
+        # first outermost method and thereafter the old `summaries.empty?`
+        # gate disabled the memo for every nested call, re-walking the shared
+        # sub-readers combinatorially (~932k body evaluations for ~20 tiny
+        # methods). The computation itself lives in
+        # `compute_user_method_return`.
+        unless memo_candidate?(stack, plain_signature)
+          return compute_user_method_return(def_node, body_scope, stack, summaries,
+                                            receiver, arg_types, plain_signature)
+        end
+
+        memo = return_memo_bucket
+        memo_key = [def_node.object_id, receiver.describe(:short),
+                    arg_types.map { |type| type.describe(:short) }]
+        return memo[memo_key] if memo.key?(memo_key)
+
+        consults_before = Thread.current[SUMMARY_CONSULT_COUNTER_KEY] || 0
+        result = compute_user_method_return(def_node, body_scope, stack, summaries,
+                                            receiver, arg_types, plain_signature)
+        consults_after = Thread.current[SUMMARY_CONSULT_COUNTER_KEY] || 0
+
+        # Store only a FINAL result. If a fixpoint summary was consulted
+        # during the computation, `result` embeds a transient Kleene iterate
+        # whose value depends on the iteration in flight, so it must not be
+        # shared across call sites.
+        memo[memo_key] = result if consults_after == consults_before
+        result
+      end
+
+      # The ADR-55 recursion-guard + value-unroll + fixpoint body of
+      # user-method return inference, factored out so
+      # `infer_user_method_return` is a thin memo wrapper (the memo is
+      # the ADR-57 follow-up; this is unchanged from pre-memo behaviour).
+      def compute_user_method_return(def_node, body_scope, stack, summaries,
+                                     receiver, arg_types, plain_signature)
+        # ADR-55 slice 1: when every bound argument is value-pinned,
+        # extend the guard key with a stable descriptor of the argument
+        # *values* so distinct constant frames may recurse (e.g.
+        # `factorial(5)` folds to `Constant[120]`). Distinct constant
+        # frames are bounded by `RECURSION_UNROLL_FUEL` per outermost
+        # entry; exhaustion or value blow-up falls back to the plain
+        # `(receiver, method)` guard — today's behaviour. Non-constant
+        # args never reach this path.
+        signature = plain_signature
+        value_key = constant_argument_value_key(arg_types)
+        extended = value_key && unroll_fuel_remaining(stack).positive?
+        signature = [plain_signature, value_key] if extended
+
         if stack.include?(signature)
           BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
-          return Type::Combinator.untyped
+          # ADR-55 slice 2: in-cycle re-entries return the current assumed
+          # summary (Kleene iterate, seeded `bot`) instead of bare
+          # `untyped`. The fixpoint loop below seeds the entry on the
+          # outermost frame; if a re-entry beats it here the entry already
+          # exists. The WD4 composition: slice 1's clamp/fuel fallbacks
+          # also route here when a summary is active.
+          return consult_summary(summaries, plain_signature)
         end
 
+        # ADR-55 WD1 clamp (governing rule): the constant-arg unroll may
+        # only ever surface a fully value-pinned result; any other outcome
+        # must be byte-identical to the plain guard's `untyped`. A frame
+        # that took the extended (value-keyed) path but whose plain
+        # `(receiver, method)` signature is already on the stack — in
+        # plain form or as the plain part of an extended frame — would
+        # have been guarded before slice 1. If such a frame's body folds
+        # to a non-pinned type, the unroll surfaced a precise value the
+        # plain guard would have masked (and the body evaluator's blind
+        # spots can make that value wrong), so clamp it back to `untyped`.
+        would_have_been_guarded =
+          extended &&
+          stack.any? { |frame| plain_part(frame) == plain_signature }
+
+        context = RecursionContext.new(
+          receiver: receiver, arg_types: arg_types, plain_signature: plain_signature,
+          summaries: summaries, would_have_been_guarded: would_have_been_guarded
+        )
+        evaluate_guarded_user_method_body(def_node, body_scope, stack, signature, context)
+      end
+
+      # True when this frame's result is a candidate for the return memo:
+      # the structural preconditions, both stable across the body walk, that
+      # are necessary (but not sufficient) for a FINAL result. Sufficiency is
+      # decided post-hoc in `infer_user_method_return` by the consult-counter
+      # check (no transient fixpoint summary was read during the compute) —
+      # so unlike the prior `memoisable_return?` this deliberately does NOT
+      # require an empty `summaries` table: inert seeded-but-unconsulted
+      # entries left by unrelated outermost frames do not contaminate a
+      # result, and gating on them disabled the memo for an entire non-
+      # recursive DAG (the scaling wall). The two preconditions: no constant-
+      # arg unroll in flight (its value-keyed frames are transient) and this
+      # plain signature not itself on the recursion guard stack (else we are
+      # inside its own cycle, returning a Kleene iterate).
+      def memo_candidate?(stack, plain_signature)
+        # Read the unroll fuel WITHOUT the decrement side effect of
+        # `unroll_fuel_remaining`: a constant-arg unroll has begun iff the
+        # thread-local is set and the stack is non-empty (the `ensure` in
+        # `evaluate_guarded_user_method_body` clears it at stack-empty).
+        unroll_idle = stack.empty? || Thread.current[INFERENCE_UNROLL_FUEL_KEY].nil?
+        unroll_idle &&
+          stack.none? { |frame| plain_part(frame) == plain_signature }
+      end
+
+      # Run-scoped return-memo bucket for the current discovery
+      # generation. Keyed by the identity of the frozen `def_nodes`
+      # table so a new analysis generation (or any scope that swaps the
+      # index) transparently lands in a fresh bucket. See RETURN_MEMO_KEY.
+      def return_memo_bucket
+        store = (Thread.current[RETURN_MEMO_KEY] ||= {}.compare_by_identity)
+        store[scope.discovered_def_nodes] ||= {}
+      end
+
+      # Pushes the recursion-guard frame, evaluates the body (the outermost
+      # frame for a plain signature runs the ADR-55 slice 2 fixpoint; nested
+      # extended frames evaluate once and let the owner iterate), and on the
+      # way out pops the frame and resets the per-outermost-entry fuel and
+      # summary tables when the guard stack drains to empty.
+      def evaluate_guarded_user_method_body(def_node, body_scope, stack, signature, context)
+        # The outermost frame for this plain signature owns the summary
+        # entry and runs the fixpoint loop. ADR-55 WD2.
+        outermost = stack.none? { |frame| plain_part(frame) == context.plain_signature }
         stack.push(signature)
         begin
-          type, _post = body_scope.evaluate(def_node.body)
-          type
+          if outermost
+            fixpoint_user_method_return(def_node, body_scope, context)
+          else
+            type, = evaluate_body_with_returns(body_scope, def_node.body)
+            clamp_unroll_result(type, context.would_have_been_guarded)
+          end
         ensure
           stack.pop
+          if stack.empty?
+            Thread.current[INFERENCE_UNROLL_FUEL_KEY] = nil
+            Thread.current[INFERENCE_SUMMARY_KEY] = nil
+            Thread.current[SUMMARY_CONSULT_DEPTHS_KEY] = nil
+          end
+        end
+      end
+
+      # Evaluates a method body and joins the value types of every explicit
+      # `return value` reached during the walk with the body's tail type.
+      #
+      # The tail-only evaluator (`statements_type_for` → `type_of(body.last)`)
+      # models only the fall-through value; an early `return false` or a
+      # block-internal `return x` produces `Bot` at its own position and is
+      # otherwise invisible to method-return inference. Without this join a
+      # predicate helper shaped `return false unless cond; ...; true` infers
+      # `Constant[true]` (the early `return false` dropped), which folds
+      # `if helper` to always-truthy. `StatementEvaluator.with_return_sink`
+      # collects the returns (nested `def`/lambda are barriers; block-internal
+      # returns correctly bubble to the enclosing method) so the inferred
+      # return is `tail | return_1 | … | return_n`, matching Ruby semantics.
+      def evaluate_body_with_returns(body_scope, body)
+        (type, post_scope), returns = StatementEvaluator.with_return_sink do
+          body_scope.evaluate(body)
+        end
+        joined = returns.empty? ? type : Type::Combinator.union(type, *returns)
+        [joined, post_scope]
+      end
+
+      # ADR-55 slice 2 — Kleene fixpoint over a recursive method's return
+      # summary. Seeds the assumption to `bot`, evaluates the body, and (only
+      # if the summary was actually consulted during evaluation — i.e. the
+      # method really recursed) iterates: if the computed return is subsumed
+      # by the assumption the fixpoint is reached; otherwise the assumption
+      # joins in the computed return and the body re-evaluates. Capped at
+      # `RECURSION_FIXPOINT_CAP` total evaluations; the final permitted
+      # iteration widens value-pinned constituents to their nominal base to
+      # force convergence, and any residual instability collapses to
+      # `untyped` (today's behaviour).
+      def fixpoint_user_method_return(def_node, body_scope, context, widened: false)
+        plain_signature = context.plain_signature
+        summaries = context.summaries
+        depth = seed_fixpoint_summary(summaries, plain_signature)
+        consult_depths = (Thread.current[SUMMARY_CONSULT_DEPTHS_KEY] ||= [])
+        computed = nil
+
+        RECURSION_FIXPOINT_CAP.times do |iteration|
+          summaries[plain_signature][:consulted] = false
+          consult_mark = consult_depths.size
+          type, = evaluate_body_with_returns(body_scope, def_node.body)
+          computed = clamp_unroll_result(type, context.would_have_been_guarded)
+
+          # Cross-signature mutual recursion (ADR-55 soundness fix,
+          # 2026-06-12): the evaluation consulted an ANCESTOR signature's
+          # in-flight summary (seed depth shallower than this frame's), so
+          # `computed` embeds a transient foreign Kleene iterate -- e.g.
+          # `odd?` folding `even?`'s seeded `bot` into `Constant[false]`.
+          # The per-signature iteration below cannot converge such an
+          # entangled pair (each side's iterate is conditioned on the
+          # other's unfinished assumption), so degrade this frame to the
+          # sound `untyped` floor instead of surfacing a one-sided value.
+          if consult_depths[consult_mark..].any? { |d| d < depth }
+            return degrade_entangled_fixpoint(summaries, plain_signature)
+          end
+
+          # The summary was never consulted — the method did not recurse on
+          # this evaluation, so there is no fixpoint to chase. Return the
+          # computed type directly (pre-fixpoint behaviour for non-recursive
+          # bodies that merely share `infer_user_method_return`).
+          return computed unless summaries.dig(plain_signature, :consulted)
+
+          # ADR-55 slice 2 bot-collapse fix (2026-06-11). When the recursive
+          # method's only contribution this evaluation was the seeded `bot`
+          # assumption (so `computed` is `bot` even though the body recursed),
+          # the `joined == assumption` check below would trivially converge at
+          # the seed and return `bot` — UNSOUND for a method with a reachable
+          # non-recursive exit (`passthrough` returns `:done`, `pick` returns
+          # `nil`). `bot` means "never returns", which feeds ADR-47
+          # reachability / always-falsey diagnostics, so it must be reserved
+          # for genuinely diverging methods (`spin`).
+          if computed.is_a?(Type::Bot)
+            resolved = resolve_bot_collapse(def_node, context, widened: widened)
+            return resolved unless resolved.nil?
+          end
+
+          step = fixpoint_step(summaries, plain_signature, computed, iteration)
+          return step unless step == :continue
+        end
+      end
+
+      # Seeds the thread-local summary entry for a fixpoint owner: the `bot`
+      # Kleene seed plus the guard-stack depth at seed time (the frame for
+      # this signature is already pushed), which `consult_summary` logs so
+      # nested fixpoints can detect a foreign in-flight (ancestor) consult.
+      # Returns the seed depth. ADR-55 slice 2.
+      def seed_fixpoint_summary(summaries, plain_signature)
+        depth = (Thread.current[INFERENCE_GUARD_KEY] || []).size
+        summaries[plain_signature] = {
+          assumption: Type::Combinator.bot, consulted: false, depth: depth
+        }
+        depth
+      end
+
+      # Degrades an entangled mutual-recursion fixpoint to the sound
+      # `untyped` floor (ADR-55 mutual-recursion soundness fix, 2026-06-12),
+      # parking `untyped` in the assumption so any consumer that still reads
+      # this signature's summary sees the floor, not the stale `bot` seed.
+      def degrade_entangled_fixpoint(summaries, plain_signature)
+        BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+        summaries[plain_signature][:assumption] = Type::Combinator.untyped
+        Type::Combinator.untyped
+      end
+
+      # One Kleene-iteration step of the fixpoint loop. Joins `computed` into
+      # the running assumption (widening value-pinned constituents on the
+      # final permitted iteration to force convergence) and either returns a
+      # final type — convergence, or the capped `untyped` collapse — or
+      # `:continue` to request another body evaluation, having advanced the
+      # stored assumption. ADR-55 WD2.
+      def fixpoint_step(summaries, plain_signature, computed, iteration)
+        assumption = summaries[plain_signature][:assumption]
+        last_iteration = iteration == RECURSION_FIXPOINT_CAP - 1
+        candidate = last_iteration ? widen_value_pinned(computed) : computed
+        joined = Type::Combinator.union(assumption, candidate)
+
+        # Convergence: the assumption already subsumes the computed return
+        # (joining it back changes nothing).
+        return candidate if joined == assumption
+
+        if last_iteration
+          # Out of iterations and still unstable — collapse to today's
+          # widening behaviour.
+          BudgetTrace.hit(BudgetTrace::RECURSION_FIXPOINT_CAP)
+          summaries[plain_signature][:assumption] = Type::Combinator.untyped
+          return Type::Combinator.untyped
+        end
+
+        summaries[plain_signature][:assumption] = joined
+        :continue
+      end
+
+      # Rebuilds the user-method body scope with every bound positional
+      # parameter widened to its nominal base (`1 | 2 | 3` → `Integer`,
+      # `Constant[:x]` → `Symbol`). Used by the bot-collapse retry in
+      # `fixpoint_user_method_return`: call-site argument narrowing can prune a
+      # recursive method's base case, and widening restores the declared-type
+      # view under which the base case is reachable. Returns `nil` when the
+      # parameter shape is not inferable (mirrors `build_user_method_body_scope`).
+      def widened_user_method_body_scope(def_node, receiver, arg_types)
+        widened_args = arg_types.map { |arg_type| widen_value_pinned(arg_type) }
+        build_user_method_body_scope(def_node, receiver, widened_args)
+      end
+
+      # ADR-55 slice 2 bot-collapse resolution (2026-06-11). Called when a
+      # fixpoint iteration computed `bot` for a recursive body. Two escape
+      # hatches keep `bot` reserved for genuinely diverging methods:
+      #
+      #   1. Re-run the fixpoint ONCE over a parameter-widened body scope
+      #      (`1 | 2 | 3` → `Integer`): call-site argument narrowing can prune
+      #      a base-case *tail* branch (`n <= 0 ? :done : recurse` with a
+      #      positive-only `n`), and widening un-prunes it so the base
+      #      constituent (`:done`) surfaces. `passthrough` recovers here.
+      #
+      #   2. If the (possibly widened) body STILL computes `bot` but contains
+      #      a reachable explicit `return` — whose value the tail-only body
+      #      evaluator never folds into the result (`pick`'s `return nil`) —
+      #      fall to the conservative `Dynamic[top]` floor (the pre-slice-2
+      #      observable) rather than the unsound `bot`.
+      #
+      # Returns the resolved type, or `nil` to let the caller's normal
+      # fixpoint convergence proceed (genuine divergence — `spin`).
+      def resolve_bot_collapse(def_node, context, widened:)
+        unless widened
+          widened_scope = widened_user_method_body_scope(def_node, context.receiver, context.arg_types)
+          return fixpoint_user_method_return(def_node, widened_scope, context, widened: true) unless widened_scope.nil?
+        end
+
+        return Type::Combinator.untyped if body_has_explicit_return?(def_node.body)
+
+        nil
+      end
+
+      # True when `node` contains a reachable explicit `return` statement —
+      # one not nested inside a return barrier (`def` / lambda / block). The
+      # tail-only body evaluator in `infer_user_method_return` never folds an
+      # early-return value into the method result, so a recursive method whose
+      # base case is spelled as `return value` (rather than a tail branch)
+      # looks like it only diverges. This detector is the signal that such a
+      # method has a non-recursive exit, so its bot-collapse must floor to
+      # `Dynamic[top]` rather than `bot` (ADR-55 slice 2, 2026-06-11).
+      RETURN_BARRIER_NODES = [Prism::DefNode, Prism::LambdaNode, Prism::BlockNode].freeze
+      private_constant :RETURN_BARRIER_NODES
+
+      def body_has_explicit_return?(node)
+        return false unless node.is_a?(Prism::Node)
+        return false if RETURN_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
+        return true if node.is_a?(Prism::ReturnNode)
+
+        node.compact_child_nodes.any? { |child| body_has_explicit_return?(child) }
+      end
+
+      # Returns the current assumed summary for `plain_signature`, recording
+      # that it was consulted (so the fixpoint owner knows the body actually
+      # recursed). Falls back to `untyped` when no summary is active — e.g. a
+      # nested extended frame guarded before its plain signature seeded an
+      # entry, which is the pre-slice-2 observable.
+      def consult_summary(summaries, plain_signature)
+        entry = summaries[plain_signature]
+        return Type::Combinator.untyped if entry.nil?
+
+        entry[:consulted] = true
+        (Thread.current[SUMMARY_CONSULT_DEPTHS_KEY] ||= []) << entry[:depth]
+        entry[:assumption]
+      end
+
+      # ADR-55 WD1 governing-rule clamp. When the just-evaluated frame
+      # took the extended (value-keyed) path but its plain signature was
+      # already guarded (`would_have_been_guarded`), the unroll may only
+      # surface a fully value-pinned result; any other outcome must be
+      # byte-identical to the plain guard's `untyped` (and counts a
+      # `RECURSION_GUARD` hit, matching the pre-slice-1 observable).
+      def clamp_unroll_result(type, would_have_been_guarded)
+        return type unless would_have_been_guarded && !fully_value_pinned?(type)
+
+        BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+        # ADR-55 WD1 clamp: a guarded extended frame whose body is non-pinned
+        # must be byte-identical to the plain guard's `untyped`. This path
+        # deliberately does NOT route to the in-progress fixpoint summary:
+        # the summary is a Kleene lower bound mid-iteration, while the clamp
+        # is a soundness backstop for an untrustworthy unrolled value, so it
+        # must stay the conservative `untyped` upper bound. (WD4's
+        # summary-composition applies to the in-cycle guard and fuel paths,
+        # which DO return the assumed summary — see `consult_summary`.)
+        Type::Combinator.untyped
+      end
+
+      # Widens every value-pinned constituent of `type` to its nominal base
+      # (`Constant[1]` → `Integer`, `Tuple[Constant…]` → its element bases),
+      # leaving non-pinned constituents untouched. Used on the fixpoint's
+      # final permitted iteration (ADR-55 WD2) to force convergence — the
+      # tower of distinct constant iterates collapses to one nominal type.
+      def widen_value_pinned(type)
+        Type::Combinator.widen_value_pinned(type)
+      end
+
+      # Consumes one unit from the thread-local unroll-fuel counter and
+      # returns the units that were available *before* this consumption
+      # (so a positive return means the extended value-key may be used).
+      # Fuel is per-outermost inference entry: at the top level (empty
+      # guard stack) it seeds to `RECURSION_UNROLL_FUEL`, and the
+      # `ensure` in `infer_user_method_return` clears it once the stack
+      # drains back to empty. On exhaustion (return 0) it records a
+      # `RECURSION_UNROLL_FUEL` hit so the caller keeps the plain
+      # `(receiver, method)` signature — today's behaviour.
+      def unroll_fuel_remaining(stack)
+        remaining = Thread.current[INFERENCE_UNROLL_FUEL_KEY]
+        remaining = RECURSION_UNROLL_FUEL if remaining.nil? || stack.empty?
+        if remaining.positive?
+          Thread.current[INFERENCE_UNROLL_FUEL_KEY] = remaining - 1
+        else
+          BudgetTrace.hit(BudgetTrace::RECURSION_UNROLL_FUEL)
+        end
+        remaining
+      end
+
+      # A stable, hashable descriptor of the argument values when EVERY
+      # element of `arg_types` is value-pinned: a `Type::Constant`, or a
+      # `Type::Tuple` whose elements are (recursively) all value-pinned.
+      # Returns nil when any argument is not value-pinned (the ordinary
+      # type-keyed path) or when any pinned value's structural size
+      # exceeds `RECURSION_VALUE_SIZE_CAP` (value blow-up → fall back).
+      def constant_argument_value_key(arg_types)
+        return nil if arg_types.empty?
+
+        keys = []
+        arg_types.each do |arg|
+          descriptor = pinned_value_descriptor(arg)
+          return nil if descriptor.nil?
+
+          keys << descriptor
+        end
+        return nil if keys.sum { |_, size| size } > RECURSION_VALUE_SIZE_CAP
+
+        keys.map(&:first)
+      end
+
+      # Returns `[descriptor, structural_size]` for a value-pinned type,
+      # or nil for anything else. Strings count by a cheap length proxy
+      # (length > 256 ≈ 64+ nodes) so a long built string disqualifies
+      # the frame without a deep walk; tuples recurse.
+      def pinned_value_descriptor(arg)
+        case arg
+        when Type::Constant
+          value = arg.value
+          size = value.is_a?(String) ? (value.length / 4) + 1 : 1
+          [["c", arg.describe(:short)], size]
+        when Type::Tuple
+          parts = []
+          total = 1
+          arg.elements.each do |element|
+            descriptor = pinned_value_descriptor(element)
+            return nil if descriptor.nil?
+
+            parts << descriptor.first
+            total += descriptor.last
+          end
+          [["t", parts], total]
         end
       end
 
@@ -1825,6 +2640,200 @@ module Rigor
         value.to_a.map { |v| Type::Combinator.constant_of(v) }
       end
 
+      INJECT_METHODS = Set[:inject, :reduce].freeze
+      private_constant :INJECT_METHODS
+
+      # Cap on the element count for the Part 2 constant-threading
+      # fold — mirrors `ReduceFolding::CONSTANT_FOLD_ELEMENT_CAP`. The
+      # size is checked BEFORE enumeration so `(1..1_000_000)` declines
+      # without materialising.
+      INJECT_CONSTANT_ELEMENT_CAP = 64
+      private_constant :INJECT_CONSTANT_ELEMENT_CAP
+
+      # Magnitude cap on a folded Integer accumulator — mirrors
+      # `ReduceFolding`'s bit cap so factorial-style blow-up declines
+      # to the Part 1 nominal result rather than parking a heavy
+      # bignum literal in the type graph.
+      INJECT_CONSTANT_BIT_CAP = 256
+      private_constant :INJECT_CONSTANT_BIT_CAP
+
+      # Block-form `inject` / `reduce` return-type fold.
+      #
+      # Part 1 (soundness): the accumulator of a block-form fold must
+      # reach a fixpoint over an unknown number of iterations — the
+      # RBS tier's generic `(S) { (S, E) -> S } -> S` binds `S` from a
+      # SINGLE block pass (acc=seed, elem=element-join), so
+      # `(1..5).inject(1) { |a, i| a * i }` types `int<1, 5>` while the
+      # runtime is 120 (out of range — unsound). We iterate the
+      # accumulator type to a capped fixpoint (ADR-55/56 `BodyFixpoint`)
+      # so the multiply converges to `Integer`, never a value-bounded
+      # interval the runtime escapes.
+      #
+      # Part 2 (precision): when the receiver is a fully-constant
+      # finite collection (`Constant[Range]` / `Tuple` of `Constant`),
+      # the seed is `Constant` (or the no-seed first element), and the
+      # block body folds to a `Constant` on EVERY iteration with the
+      # running accumulator + element bound, thread the accumulator
+      # through per-element block evaluation and return the final
+      # `Constant` (`(1..5).inject(1) { |a, i| a * i } -> 120`).
+      #
+      # The two are layered: Part 2 is attempted first (a constant
+      # answer is strictly tighter); on any decline it falls through to
+      # the Part 1 sound nominal fixpoint, and on a Part 1 decline to
+      # the RBS tier. Captured-local write-back (ADR-56) runs at the
+      # statement level independent of this return-type computation, so
+      # a block that both accumulates and mutates captured state keeps
+      # its write-back regardless of which arm answers here.
+      #
+      # @return [Rigor::Type, nil]
+      def try_block_inject_fold(call_node, receiver, arg_types)
+        return nil unless INJECT_METHODS.include?(call_node.name)
+
+        block = call_node.block
+        return nil unless block.is_a?(Prism::BlockNode)
+
+        seed, has_seed = inject_seed(arg_types)
+        return nil if arg_types.size > (has_seed ? 1 : 0)
+
+        constant = try_constant_inject_fold(receiver, block, seed, has_seed)
+        return constant if constant
+
+        try_nominal_inject_fixpoint(receiver, block, seed, has_seed)
+      end
+
+      # Splits the positional args into the optional seed. A Symbol
+      # final arg (`inject(seed, :*)`) is the no-block Symbol form and
+      # never reaches here (the block guard already failed for it).
+      #
+      # @return [Array(Rigor::Type, nil), Boolean] `[seed, has_seed]`
+      def inject_seed(arg_types)
+        case arg_types.size
+        when 0 then [nil, false]
+        else [arg_types.first, true]
+        end
+      end
+
+      # Part 2 — thread the accumulator through per-element block
+      # evaluation over a fully-constant finite receiver. Declines
+      # (nil) on a non-constant receiver / seed, a size or magnitude
+      # cap, or any per-step result that is not a foldable `Constant`.
+      def try_constant_inject_fold(receiver, block, seed, has_seed)
+        members = inject_constant_members(receiver)
+        return nil if members.nil?
+
+        acc, rest = inject_constant_start(members, seed, has_seed)
+        return nil if acc.nil?
+
+        rest.each do |element_value|
+          acc = inject_constant_step(block, acc, element_value)
+          return nil if acc.nil?
+        end
+        acc
+      end
+
+      # Extracts the receiver's foldable constant values, size-capped
+      # before enumeration, or nil to decline.
+      def inject_constant_members(receiver)
+        case receiver
+        when Type::Constant then inject_constant_range_members(receiver.value)
+        when Type::Tuple then inject_constant_tuple_members(receiver.elements)
+        end
+      end
+
+      def inject_constant_range_members(value)
+        return nil unless value.is_a?(Range)
+
+        first = value.begin
+        last = value.end
+        return nil unless inject_foldable?(first) && inject_foldable?(last)
+
+        size = value.size
+        return nil unless size.is_a?(Integer)
+        return nil if size > INJECT_CONSTANT_ELEMENT_CAP
+
+        value.to_a
+      rescue StandardError
+        nil
+      end
+
+      def inject_constant_tuple_members(elements)
+        return nil if elements.size > INJECT_CONSTANT_ELEMENT_CAP
+        return nil unless elements.all? { |e| e.is_a?(Type::Constant) && inject_foldable?(e.value) }
+
+        elements.map(&:value)
+      end
+
+      # Seeds the constant accumulator: with a seed the memo starts at
+      # the (foldable) seed value and every member is folded; without a
+      # seed the first member seeds the memo and the rest are folded.
+      # The accumulator is carried as a `Constant` type (so the block
+      # body sees a value-pinned param).
+      #
+      # @return [Array(Rigor::Type::Constant, nil), Array] `[acc, rest]`
+      def inject_constant_start(members, seed, has_seed)
+        if has_seed
+          return [nil, []] unless seed.is_a?(Type::Constant) && inject_foldable?(seed.value)
+
+          [seed, members]
+        else
+          return [nil, []] if members.empty?
+
+          [Type::Combinator.constant_of(members.first), members[1..]]
+        end
+      end
+
+      # Evaluates the block body once with the running constant
+      # accumulator + the next constant element bound to the block
+      # params, returning the result when it is a foldable `Constant`
+      # within the magnitude cap, else nil to decline the whole fold.
+      def inject_constant_step(block, acc, element_value)
+        element = Type::Combinator.constant_of(element_value)
+        result = type_block_body_with_param(block, [acc, element])
+        return nil unless result.is_a?(Type::Constant)
+        return nil unless inject_foldable?(result.value)
+        return nil if inject_magnitude_too_large?(result.value)
+
+        result
+      end
+
+      INJECT_FOLDABLE_CLASSES = [Integer, Float, Rational].freeze
+      private_constant :INJECT_FOLDABLE_CLASSES
+
+      def inject_foldable?(value)
+        INJECT_FOLDABLE_CLASSES.any? { |klass| value.is_a?(klass) }
+      end
+
+      def inject_magnitude_too_large?(value)
+        value.is_a?(Integer) && value.bit_length > INJECT_CONSTANT_BIT_CAP
+      end
+
+      # Part 1 — the sound nominal accumulator fixpoint. Iterates
+      # `acc = join(acc, block(acc, element))` to a capped fixpoint with
+      # final `Constant -> Nominal` widening (ADR-55/56 `BodyFixpoint`),
+      # seeding `acc` from the seed type (or the element type for the
+      # no-seed form) and binding the element-join to the element param.
+      # Declines (nil) when the element type is unknown so the RBS tier
+      # owns the call.
+      def try_nominal_inject_fixpoint(receiver, block, seed, has_seed)
+        element = MethodDispatcher::IteratorDispatch.element_type_of(receiver)
+        return nil if element.nil?
+
+        seed_acc = has_seed ? seed : element
+        return nil if seed_acc.nil?
+
+        converged = BodyFixpoint.converge(
+          names: [:__inject_acc__],
+          seed_bindings: { __inject_acc__: seed_acc },
+          widen: method(:widen_value_pinned),
+          evaluate_body: lambda do |bindings|
+            acc = bindings[:__inject_acc__]
+            result = type_block_body_with_param(block, [acc, element])
+            result.nil? ? {} : { __inject_acc__: result }
+          end
+        )
+        converged[:__inject_acc__] || seed_acc
+      end
+
       # `index(value)` and `find_index(value)` carry a positional
       # argument and search by `==` rather than running the block.
       # Decline so the RBS tier owns those forms.