rigortype 0.3.6 → 0.3.8

data/lib/rigor/inference/expression_typer.rb

@@ -7,10 +7,14 @@ require_relative "../reflection"
 require_relative "../ast"
 require_relative "../source/constant_path"
 require_relative "../source/node_children"
+require_relative "../source/node_walker"
 require_relative "../analysis/self_call_resolution_recorder"
 require_relative "block_parameter_binder"
+require_relative "method_parameter_binder"
 require_relative "body_fixpoint"
 require_relative "budget_trace"
+require_relative "captured_locals"
+require_relative "def_node_resolver"
 require_relative "dynamic_origin"
 require_relative "origin_lookup"
 require_relative "../effects/collector"
@@ -19,10 +23,13 @@ require_relative "flow_tracer"
 require_relative "indexed_narrowing"
 require_relative "macro_block_self_type"
 require_relative "method_dispatcher"
+require_relative "mutation_widening"
 require_relative "narrowing"
+require_relative "receiver_alias"
 require_relative "singleton_object_constant"
 require_relative "optimistic_origin"
 require_relative "struct_fold_safety"
+require_relative "version_guard"
 
 module Rigor
   module Inference
@@ -51,7 +58,7 @@ module Rigor
     # docs/internal-spec/inference-engine.md. The optional tracer is a Rigor::Inference::FallbackTracer (or
     # any object answering #record_fallback) that receives a Fallback event for each fallback; the tracer
     # MUST NOT change the return value of type_of.
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class ExpressionTyper
       # Hash-based dispatch keeps `type_of` linear and lets future slices add node kinds without growing a
       # single case statement past RuboCop's cyclomatic budget. Anonymous Prism subclasses are not expected.
@@ -83,6 +90,9 @@ module Rigor
         Prism::ProgramNode => :type_of_program,
         # Calls
         Prism::CallNode => :call_type_for,
+        Prism::CallOrWriteNode => :call_or_write_type_for,
+        Prism::CallAndWriteNode => :call_and_write_type_for,
+        Prism::CallOperatorWriteNode => :call_operator_write_type_for,
         Prism::ArgumentsNode => :type_of_non_value,
         # Constants
         Prism::ConstantReadNode => :type_of_constant_read,
@@ -421,11 +431,16 @@ module Rigor
         resolve_constant_name(node.name.to_s) || unresolved_constant_fallback(node, node.name.to_s)
       end
 
+      # A leading `::` (`::Rails`, `::Rails::Application`) is Ruby's escape hatch out of the lexical ladder:
+      # it names the top-level constant whatever the enclosing nesting defines. The rendered name is
+      # deliberately un-rooted (the discovery tables are keyed that way), so the marker rides alongside it
+      # into the resolver (#614).
       def type_of_constant_path(node)
         full_name = Source::ConstantPath.qualified_name_or_nil(node)
         return fallback_for(node, family: :prism) if full_name.nil?
 
-        resolve_constant_name(full_name) || unresolved_constant_fallback(node, full_name)
+        resolve_constant_name(full_name, rooted: Source::ConstantPath.rooted?(node)) ||
+          unresolved_constant_fallback(node, full_name)
       end
 
       # ADR-82 WD9 — an unresolved constant whose root name a locked, RBS-less gem declares carries the
@@ -436,6 +451,7 @@ module Rigor
       # `Dynamic[top]`, and an unindexed constant (project typo, unanalyzed project path) keeps the generic
       # cause: the fail-open direction is a missing label, never a wrong one.
       def unresolved_constant_fallback(node, full_name)
+        record_missing_constant(full_name) if Analysis::DependencyRecorder.active?
         root = full_name.delete_prefix("::").split("::").first
         owner = root && scope.environment.missing_rbs_gem_owner(root)
         return fallback_for(node, family: :prism) unless owner
@@ -446,13 +462,50 @@ module Rigor
         inner
       end
 
+      # ADR-46 slice 3 / issue #622 — a constant reference that resolved to NOTHING is a negative cross-file
+      # dependency: a file declaring that constant later must re-check every file that read it as missing.
+      # Without this edge the structural tier had no record of the read at all — `read_missing(:method, …)`
+      # fires only once the receiver constant has RESOLVED and the method lookup misses, so a missing
+      # constant short-circuited before any edge existed, and a warm `--incremental` run kept
+      # `Rails.logger`'s `Dynamic[top]` (and missed the `call.undefined-method` a full run fires) after a
+      # later edit added `module Rails`.
+      #
+      # Reuses the existing `class:Name` negative kind (`CheckRules`'s override-ancestor miss records the
+      # same one) rather than adding a `constant:` kind, because the producer that has to invert it already
+      # exists: `Incremental.appeared_classes` reports a newly declared class / module by its QUALIFIED name
+      # and `negative_affected` matches it by simple (last-segment) name. The snapshot row grammar is
+      # therefore unchanged — no `IncrementalSnapshot::SCHEMA` bump — and a snapshot recorded by an engine
+      # without this edge is already dropped by the fingerprint's engine-source part.
+      #
+      # The LAST segment is the whole key, and one row per reference is the whole cost: a qualified read
+      # resolves only once its final segment is declared, and every constant form that resolves cross-file —
+      # a `class` / `module`, and the constant-assigned `Data.define` / `Struct.new` forms — registers in the
+      # discovery pre-pass's class sources under its qualified name, so its final segment always appears.
+      # (A plain value constant, `FOO = 1` or a `VERSION` nested in a module, resolves in NO cross-file read
+      # today, so there is nothing for a root-segment or a `constant:` key to salvage; if that changes, the
+      # answer is a producer that reports appeared value constants, not a wider key here.) Simple-name
+      # matching over-invalidates — a nested `MyApp::Rails` also re-checks a reader of the top-level `Rails`
+      # — which is the sound direction and the grammar the class negatives already use. Consumers hold
+      # `missing` as a Set, so a name repeated across a file still costs one row.
+      def record_missing_constant(full_name)
+        segments = full_name.delete_prefix("::").split("::")
+        return if segments.empty?
+
+        Analysis::DependencyRecorder.read_missing(:class, segments.last)
+        # Issue #644's `constant:<last segment>` edge is NOT recorded here. It is recorded once per
+        # reference by `Reflection.resolve_constant_type`, before the resolver ladder runs, so it covers a
+        # reference that resolves through RBS or the class registry as well as one that misses — all three
+        # answers move when the project's constant write set moves. Recording it again on this path would be
+        # a second source of truth for the same key.
+      end
+
       # Resolves a constant reference through Ruby's lexical constant lookup. Delegates to the shared
       # `Reflection.resolve_constant_type` owner so the same walk (registry singleton, discovered class,
       # in-source value, RBS constant, across the peeled `::` prefix candidates) is reused by
       # `Inference::Narrowing`'s `Constant[Regexp]` match-operand recognition. Returns the matched
       # `Rigor::Type` or nil; the caller decides whether to fall back.
-      def resolve_constant_name(name)
-        Reflection.resolve_constant_type(name, scope: scope)
+      def resolve_constant_name(name, rooted: false)
+        Reflection.resolve_constant_type(name, scope: scope, rooted: rooted)
       end
 
       # Slice 5 phase 1 upgrades hash literals to `HashShape{...}` when every entry is a static `AssocNode`
@@ -642,6 +695,14 @@ module Rigor
       # `Constant[false]` fold one branch; `Union[true, false]`, `Dynamic[T]`, and `Top` keep both branches live.
       def constant_predicate_polarity(predicate)
         return nil if predicate.nil?
+
+        # ADR-47 WD5 — a decidable version guard (#627) answers first, exactly as it does on the scope side
+        # in `StatementEvaluator#branch_certainty`. Both readers ask the same pure function of the AST, so
+        # the expression form (`RUBY_VERSION >= "3.1" ? a : b`) and the statement form cannot disagree about
+        # which arm survives. The verdict rests on literals, so the ADR-101 optimistic-carrier decline below
+        # — which guards an RBS-derived judgment — does not apply to it.
+        guard = VersionGuard.verdict(predicate)
+        return guard if guard
         # ADR-101 — decline on an optimistically nil-free carrier; see
         # `StatementEvaluator#optimistic_carrier?` for why the gate is here and not in `Narrowing`.
         return nil unless optimistic_origin_for(predicate).nil?
@@ -957,10 +1018,10 @@ module Rigor
         end
       end
 
-      def fallback_for(node, family:)
+      def fallback_for(node, family:, origin: DynamicOrigin::UNSUPPORTED_SYNTAX)
         inner = dynamic_top
-        record_fallback(node, family: family, inner_type: inner, origin: DynamicOrigin::UNSUPPORTED_SYNTAX)
-        scope.record_dynamic_origin(node, DynamicOrigin::UNSUPPORTED_SYNTAX)
+        record_fallback(node, family: family, inner_type: inner, origin: origin)
+        scope.record_dynamic_origin(node, origin)
         inner
       end
 
@@ -1107,9 +1168,19 @@ module Rigor
       # Issue #316 — the lookup goes through the confidence-gated `Scope#bindable_top_level_def_for`, not the
       # raw table: inside a block whose `self` is unmodelled, a top-level `def` from ANOTHER file is not
       # evidence about which method the call reaches, so the bind is declined and the call widens.
+      #
+      # Issue #618 — the binding is a fallback for names the enclosing `self` does NOT answer, not a
+      # first-choice tier. A top-level `def` is a private method on `Object`, the last link of every MRO, so
+      # whenever the call's own `self` carries the name the class wins at runtime and the top-level body is
+      # never reached. Binding regardless of `self_type` inverted that: a top-level `def text` typed the
+      # member read inside `class Line < Struct.new(:text); def shout = text.upcase; end` as the def's `nil`
+      # and fired `undefined method 'upcase' for nil` on correct code. The candidate is still looked up
+      # first — that lookup is a hash probe and owns the ADR-46 cross-file dependency edge — and
+      # {#self_type_answers?} then vetoes the bind for a name the enclosing class answers itself.
       def try_local_def_dispatch(node, receiver, arg_types)
         local_def = node.receiver.nil? ? scope.bindable_top_level_def_for(node.name) : nil
         return nil unless local_def
+        return nil if self_type_answers?(node.name)
 
         local_inference = infer_top_level_user_method(local_def, receiver, arg_types)
         return local_inference if local_inference
@@ -1123,15 +1194,193 @@ module Rigor
         dynamic_top
       end
 
+      # Issue #618 — whether the call's enclosing `self` already answers `method_name`. Only a `self` whose
+      # class is KNOWN participates: at genuine top level, and inside a block whose `self` is unmodelled,
+      # `scope.self_type` is nil, the predicate is false, and the historical top-level binding stands — that
+      # is #316's / #319's territory and this veto stays out of it.
+      #
+      # The ADR-48 member carriers answer from their own map first: a `StructInstance` / `DataInstance`
+      # `self` carries the member set the body reads through, and an anonymous `Struct.new(...)` value has no
+      # class name to look anything else up under.
+      def self_type_answers?(method_name)
+        case (self_type = scope.self_type)
+        when Type::Singleton then singleton_self_answers?(self_type.class_name, method_name)
+        when Type::Nominal then instance_self_answers?(self_type.class_name, method_name)
+        when Type::StructInstance, Type::DataInstance
+          self_type.members.key?(method_name.to_sym) || instance_self_answers?(self_type.class_name, method_name)
+        else false
+        end
+      end
+
+      # The instance side of {#self_type_answers?}: the class's own discovered methods (`def`, `attr_*`,
+      # `define_method`, `alias`), its `Struct.new` / `Data.define` member accessors, a `def` reached through
+      # its project ancestors (superclass chain and included modules), and an RBS method declared on the
+      # class ITSELF.
+      #
+      # The RBS arm is own-class only, deliberately. An inherited-declaration test would match every
+      # `Object` / `Kernel` / `Enumerable` name and retract the binding v0.0.3 A exists for — a `def
+      # select(...)` collocated with its DSL-block call site would route straight back through
+      # `Enumerable#select`.
+      def instance_self_answers?(class_name, method_name)
+        return false if class_name.nil?
+        return true if scope.discovered_method?(class_name, method_name, :instance)
+        return true if meta_member?(class_name, method_name)
+        return true if resolve_user_def_through_ancestors(class_name, method_name)
+
+        rbs_declared_on_class?(safe_rbs_method_definition(class_name, method_name, :instance), class_name)
+      end
+
+      # The singleton side: a class-body `self` is `Singleton[Foo]`, where an implicit-self call reaches
+      # `Foo`'s own class methods before `Object`'s private top-level `def`.
+      def singleton_self_answers?(class_name, method_name)
+        return false if class_name.nil?
+        return true if scope.discovered_method?(class_name, method_name, :singleton)
+        return true unless scope.singleton_def_for(class_name, method_name).nil?
+
+        rbs_declared_on_class?(safe_rbs_method_definition(class_name, method_name, :singleton), class_name)
+      end
+
+      # A `Struct.new(:a, :b)` / `Data.define(:a, :b)` member accessor. The layouts are a discovery table of
+      # their own, separate from `discovered_methods`, so the accessor names they imply have to be asked for
+      # explicitly. Only the reader name is tested: a writer is unreachable as an implicit-self call, since
+      # bare `a = v` is a local assignment.
+      def meta_member?(class_name, method_name)
+        layout = scope.struct_member_layout(class_name)
+        members = layout ? layout[:members] : scope.data_member_layout(class_name)
+        !members.nil? && members.include?(method_name.to_sym)
+      end
+
+      def safe_rbs_method_definition(class_name, method_name, kind)
+        if kind == :singleton
+          Rigor::Reflection.singleton_method_definition(class_name, method_name, scope: scope)
+        else
+          Rigor::Reflection.instance_method_definition(class_name, method_name, scope: scope)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # True when the RBS declaration found for the name sits on `class_name` itself rather than on an
+      # ancestor; mirrors `CheckRules#defined_on?` and `SigGen::Generator#declared_on_class_itself?`.
+      def rbs_declared_on_class?(definition, class_name)
+        return false if definition.nil?
+        return false unless definition.respond_to?(:defined_in)
+
+        defined_in = definition.defined_in
+        return false if defined_in.nil?
+
+        defined_in.to_s.delete_prefix("::") == class_name.to_s.delete_prefix("::")
+      end
+
+      # Issue #520 — Ruby defines the value of an attribute / index assignment (`x.attr = v`, `h[k] = v`)
+      # as the RHS object itself, whatever the writer method returns. The dispatch pipeline still runs
+      # first for everything it observes on the side (effect collection, provenance, recorders, and the
+      # rules' own view of the writer), but its RESULT is discarded in favor of the last argument's type —
+      # `Hash#[]=`'s declared V made `h[k] = true` read Dynamic on an untyped hash, ~300 sites across the
+      # 2026-09-01 corpus sweep. Safe-navigation writes stay on the dispatch result: `x&.attr = v` is
+      # `v | nil`, which is #518's (safe-navigation) territory, not plain value semantics.
+      def call_type_for(node)
+        return safe_navigation_call_type(node) if node.safe_navigation?
+
+        attribute_write_value(node, call_dispatch_type_for(node))
+      end
+
+      # The RHS-value override for plain attribute / index writes (#520); a non-write call keeps the
+      # dispatch result.
+      def attribute_write_value(node, result)
+        return result unless node.attribute_write?
+
+        rhs = node.arguments&.arguments&.last
+        return result if rhs.nil? || rhs.is_a?(Prism::SplatNode)
+
+        type_of(rhs)
+      end
+
+      # Issue #518 — `x&.m` is NOT a plain call: when `x` is nil the method never runs and the expression
+      # is nil. Typed as a plain call it inherited both defects of union dispatch — the nil arm's method
+      # was folded as if `&.` called it (`s&.to_s` on `String?` read `String`, missing the nil the runtime
+      # produces), and a method absent from NilClass declined the whole union to `Dynamic[top]` even when
+      # the non-nil arm is fully typed (herb's own sig declares `Token#value: String`; the `?` alone
+      # discarded it). The call is dispatched on the nil-stripped receiver and the nil the skip produces is
+      # unioned back in; a receiver that IS nil skips the call statically.
+      def safe_navigation_call_type(node)
+        # A literal `nil&.m` is the statically-skipped call and folds to nil. An INFERRED exactly-nil
+        # receiver deliberately does NOT fold: every corpus site with that shape traced to a wrong
+        # upstream nil (an `attr_writer`-backed ivar whose only static write is nil — #541 — or a mutated
+        # literal-shape constant — #540), and folding it turned those latent wrong types into
+        # `flow.always-truthy-condition` firings on working programs. Until those uplinks are honest,
+        # the inferred-nil receiver keeps the plain pipeline's Dynamic.
+        return Type::Combinator.constant_of(nil) if node.receiver.is_a?(Prism::NilNode)
+
+        receiver = type_of(node.receiver)
+        non_nil = Narrowing.narrow_non_nil(receiver)
+        # A Bot or Dynamic fragment cannot improve on the plain pipeline (Bot: the inferred-exactly-nil
+        # receivers trace to the #540 / #541 uplinks; Dynamic: the stripped dispatch re-answers Dynamic),
+        # so both keep the historical path and its flow bookkeeping.
+        return call_dispatch_type_for(node) if non_nil.is_a?(Type::Bot) || non_nil.is_a?(Type::Dynamic)
+
+        result = attribute_write_value(node, call_dispatch_type_for(node, receiver_override: non_nil))
+        # Structural equality: `narrow_non_nil` rebuilds a Union even when it removed nothing, and a
+        # receiver that cannot be nil must not have a phantom nil unioned into its result.
+        return result if non_nil == receiver
+
+        Type::Combinator.union(result, Type::Combinator.constant_of(nil))
+      end
+
+      # Issue #532 — the attribute compound-write family (`x.attr ||= v`, `&&=`, `+=`), the last
+      # genuinely unmodeled value-position constructs the 2026-09-01 corpus census found (they fell to the
+      # `unsupported_syntax` fallback). Value semantics mirror the local / ivar / index siblings:
+      # `||=` is `truthy(read) | rhs`, `&&=` is `falsey(read) | rhs`, and an operator write is the
+      # operator dispatched on the read result. A `&.`-form compound write unions the skipped-call nil in
+      # (#518's rule). Scope effects stay as before (none) — the struct member writeback and shape
+      # widening for these forms are follow-up work recorded on #532.
+      def call_or_write_type_for(node)
+        current = attribute_compound_read_type(node)
+        value = Type::Combinator.union(Narrowing.narrow_truthy(current), type_of(node.value))
+        with_compound_write_safe_nav(node, value)
+      end
+
+      def call_and_write_type_for(node)
+        current = attribute_compound_read_type(node)
+        value = Type::Combinator.union(Narrowing.narrow_falsey(current), type_of(node.value))
+        with_compound_write_safe_nav(node, value)
+      end
+
+      def call_operator_write_type_for(node)
+        current = attribute_compound_read_type(node)
+        result = MethodDispatcher.dispatch(
+          receiver_type: current, method_name: node.binary_operator, arg_types: [type_of(node.value)],
+          environment: scope.environment, call_node: node, scope: scope
+        ) || dynamic_top
+        with_compound_write_safe_nav(node, result)
+      end
+
+      def attribute_compound_read_type(node)
+        receiver = type_of(node.receiver)
+        MethodDispatcher.dispatch(
+          receiver_type: receiver, method_name: node.read_name, arg_types: [],
+          environment: scope.environment, call_node: node, scope: scope
+        ) || dynamic_top
+      end
+
+      def with_compound_write_safe_nav(node, value)
+        return value unless node.call_operator_loc&.slice == "&."
+
+        Type::Combinator.union(value, Type::Combinator.constant_of(nil))
+      end
+
       # Slice 2 routes call expressions through `MethodDispatcher`. The receiver and every argument are typed
       # first, then the dispatcher is asked for a result type. A nil result triggers the fail-soft fallback
       # for the CallNode itself (the inner type_of calls already record their own fallbacks for unrecognised
       # receivers/args, so the tracer captures both the immediate dispatch miss and the deeper cause).
-      def call_type_for(node)
+      # `receiver_override` substitutes the receiver type for the whole pipeline (folds, dispatch, the
+      # inference tiers) without re-reading the receiver node — the safe-navigation path (#518) dispatches
+      # on the nil-stripped fragment, and the optional-receiver retry (#519) re-runs the pipeline on it.
+      def call_dispatch_type_for(node, receiver_override: nil)
         narrowed = indexed_narrowing_for(node)
         return narrowed if narrowed
 
-        receiver = call_receiver_type_for(node)
+        receiver = receiver_override || call_receiver_type_for(node)
         arg_types = call_arg_types(node)
         block_type = block_return_type_for(node, receiver, arg_types)
 
@@ -1140,6 +1389,9 @@ module Rigor
         # asks nothing further of dispatch. Off (the default) this is one integer read.
         Effects::Collector.record_call(node, receiver, scope) if Effects::Collector.active?
 
+        literal_send = try_literal_send(node, receiver)
+        return literal_send if literal_send
+
         local_def_result = try_local_def_dispatch(node, receiver, arg_types)
         return local_def_result if local_def_result
 
@@ -1148,14 +1400,8 @@ module Rigor
         # the corresponding element bound to the block parameter and assemble the results into a
         # `Tuple[U_1..U_n]`. This sits ahead of `MethodDispatcher.dispatch` so the RBS tier does not re-widen
         # the answer back to `Array[union]`.
-        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
+        block_fold = try_receiver_block_folds(node, receiver, arg_types)
+        return block_fold if block_fold
 
         result = MethodDispatcher.dispatch(
           receiver_type: receiver,
@@ -1168,6 +1414,12 @@ module Rigor
         )
         return result if result
 
+        dispatch_miss_result(node, receiver, arg_types)
+      end
+
+      # The post-dispatch tiers for a call `MethodDispatcher` could not answer, in their historical
+      # order; extracted from {#call_dispatch_type_for} whole.
+      def dispatch_miss_result(node, receiver, arg_types)
         # v0.0.2 #5 — inter-procedural inference for user-defined methods. When dispatch misses but the
         # receiver is a user class with a `def` body, re-type the body with the call's argument types bound
         # and return the body's last-expression type.
@@ -1187,9 +1439,46 @@ module Rigor
         # semantic outcome, not a fail-soft compromise, so it MUST NOT record a tracer event.
         return inherit_receiver_origin(node) if receiver.is_a?(Type::Dynamic)
 
+        # Issue #519 — a `T | nil` receiver whose dispatch exhausted every tier: the nil arm vetoed the
+        # union (dispatch_union declines when ANY member declines, and the later tiers refuse unions), so
+        # `StringScanner?#scan` lost a type its RBS fully declares. Retry the whole pipeline on the
+        # non-nil fragment and answer its result: the nil path raises, which is `possible-nil-receiver`'s
+        # job (that rule reads the RECEIVER and is untouched); the value describes the path that returns
+        # (ADR-5 optimism, same polarity as the accessor-read nil-drop ADR-58 records). Unions whose
+        # non-nil members still decline fall through unchanged.
+        optional_retry = try_non_nil_receiver_retry(node, receiver)
+        return optional_retry if optional_retry
+
         unresolved_call_result(node, receiver)
       end
 
+      def try_non_nil_receiver_retry(node, receiver)
+        return nil unless receiver.is_a?(Type::Union)
+        # When NilClass DEFINES the method (`nil?`, `to_s`, `==`, `inspect`, …), the nil arm is a live
+        # returner, not the veto — the union declined on some other member, and answering the stripped
+        # receiver's result would drop the nil arm's contribution (`(Journal | nil).nil?` must never
+        # answer the non-nil arm's constant-folded `false`). Retry only when the nil path raises.
+        return nil if nil_class_defines?(node.name)
+
+        non_nil = Narrowing.narrow_non_nil(receiver)
+        # Structural equality, not identity: `narrow_non_nil` rebuilds a Union even when it removed
+        # nothing, and an identity check would send a nil-free union that exhausts dispatch through the
+        # retry forever. A Dynamic fragment is excluded too: its retry can only re-answer Dynamic, and
+        # running the pipeline twice for that non-answer perturbs the flow bookkeeping for nothing.
+        return nil if non_nil.is_a?(Type::Bot) || non_nil.is_a?(Type::Dynamic) || non_nil == receiver
+
+        call_dispatch_type_for(node, receiver_override: non_nil)
+      end
+
+      # Conservative when NilClass's definition is unavailable: without the proof that the nil path
+      # raises, the retry stays off.
+      def nil_class_defines?(method_name)
+        definition = Rigor::Reflection.instance_definition("NilClass", scope: scope)
+        return true if definition.nil?
+
+        !definition.methods[method_name.to_sym].nil?
+      end
+
       # The engine choke-point where a call has exhausted every resolution tier (RBS dispatch + user-class
       # ancestor walk) and falls through to `Dynamic[top]`. Two observational recorders read it, both a
       # plain integer read when inactive, and neither changes the answer:
@@ -1201,9 +1490,85 @@ module Rigor
         record_unresolved_self_call(node, receiver) if Analysis::SelfCallResolutionRecorder.active?
         Effects::Collector.record_unresolved(node, scope.source_path) if Effects::Collector.active?
 
-        fallback_for(node, family: :prism)
+        fallback_for(node, family: :prism, origin: unresolved_call_origin(receiver, node.name))
+      end
+
+      # Issue #522 — the honest cause for a call the tiers exhausted. When the receiver's class HAS a
+      # discovered project def for the method, the miss is a return the engine could not infer (the
+      # discovered-method tier deliberately declined in favor of body inference, which then declined too —
+      # `MethodDispatcher#try_discovered_method`'s decline arms), which is ADR-82's
+      # `INFERRED_RETURN_UNTYPED`, not "unsupported syntax". Without this, every service-object `#call`
+      # whose body defeats inference reports to `coverage --protection` as a syntax gap. The generic cause
+      # stays for genuinely unresolved names (framework DSL sends, methods no scanned file defines).
+      def unresolved_call_origin(receiver, method_name)
+        class_name, kind = case receiver
+                           when Type::Nominal then [receiver.class_name, :instance]
+                           when Type::Singleton then [receiver.class_name, :singleton]
+                           else [nil, nil]
+                           end
+        return DynamicOrigin::UNSUPPORTED_SYNTAX if class_name.nil?
+        return DynamicOrigin::INFERRED_RETURN_UNTYPED if scope.discovered_method?(class_name, method_name, kind)
+        # Issue #530 item 1 — the receiver's own class declares nothing, but its ancestry LEAVES the project
+        # into a locked gem that ships no RBS. That gem is the honest cause: the method is inherited from a
+        # class Rigor cannot see, and the user's action is `add_rbs`, not "report an engine gap".
+        return DynamicOrigin::EXTERNAL_GEM_WITHOUT_RBS if external_gem_reached_through_ancestry?(class_name)
+
+        DynamicOrigin::UNSUPPORTED_SYNTAX
+      end
+
+      # Issue #530 item 1 — whether `class_name`'s ancestry crosses out of the project into a locked, RBS-less
+      # gem. WD9's tagging keys on CONSTANT READS, which catches `Parser::AST::Node` where it is WRITTEN (the
+      # superclass position) and nothing after: every implicit-self call inherited into the subclass body —
+      # `node_parts` on rubocop-ast, and the 125-site `#[]` chain hanging off it — recorded the generic cause,
+      # so the target reported 13 add-rbs against 687 engine-gap where the honest story is a gem with no RBS.
+      #
+      # The boundary is exactly the ancestor name that resolves to NO project class. Inside the project the
+      # walk continues; the first name that leaves is the one whose root segment the missing-gem index can
+      # own. A name that leaves into a gem the index does NOT claim (RBS present, not locked, entry file
+      # unreadable) yields nothing and the generic cause stands — the fail-open direction ADR-82 requires,
+      # where the failure mode is a missing label and never a wrong one.
+      #
+      # Bounded by {Scope::ANCESTOR_WALK_LIMIT}'s spirit rather than its constant: this is a provenance
+      # side-channel on an ALREADY-unresolved call, so a deep hierarchy must cost a bounded amount and then
+      # give up rather than pay for a perfect answer nothing type-checks against.
+      def external_gem_reached_through_ancestry?(class_name)
+        environment = scope.environment
+        return false if environment.nil? || !environment.respond_to?(:missing_rbs_gem_owner)
+
+        seen = {}
+        queue = [class_name.to_s]
+        visited = 0
+        until queue.empty?
+          current = queue.shift
+          next if current.nil? || seen[current]
+
+          seen[current] = true
+          visited += 1
+          return false if visited > EXTERNAL_GEM_ANCESTRY_LIMIT
+
+          return true if ancestry_step_leaves_project?(current, queue, environment)
+        end
+        false
+      end
+
+      # One hop of {#external_gem_reached_through_ancestry?}: pushes `current`'s ancestors that stay INSIDE
+      # the project onto `queue`, and answers whether any that leaves lands in a gem the index claims.
+      def ancestry_step_leaves_project?(current, queue, environment)
+        raw_ancestors = scope.includes_of(current) + [scope.superclass_of(current)].compact
+        raw_ancestors.any? do |raw|
+          resolved = scope.ancestor_name_candidates(current, raw).find { |c| scope.known_user_class?(c) }
+          next queue.push(resolved) && false if resolved
+
+          root = raw.to_s.delete_prefix("::").split("::").first
+          !(root.nil? || environment.missing_rbs_gem_owner(root).nil?)
+        end
       end
 
+      # Deliberately smaller than the dispatch walk's cap: this answers a REPORTING question, and a hierarchy
+      # deeper than this has already told us the receiver is not a simple project class.
+      EXTERNAL_GEM_ANCESTRY_LIMIT = 16
+      private_constant :EXTERNAL_GEM_ANCESTRY_LIMIT
+
       # ADR-82 WD6 — carry the receiver's provenance onto the call it produces (returning the unchanged
       # `dynamic_top` result), so a specific cause survives a method chain (`x.foo.bar`): without this,
       # `.foo` on a Dynamic `x` records nothing and `.bar`'s receiver looks causeless. Side-channel only
@@ -1326,20 +1691,121 @@ module Rigor
         end
       end
 
-      def try_user_method_inference(receiver, call_node, arg_types)
-        return nil unless receiver.is_a?(Type::Nominal)
+      # #525 — instance-side user-method inference accepts the named ADR-48 member carriers alongside
+      # plain nominals: a `Line = Struct.new(...) do ... end` value is a StructInstance whose block defs
+      # live under "Line", and the carrier itself is the right `self` for the body (member reads inside
+      # the def project through it).
+      def user_inference_receiver?(receiver)
+        case receiver
+        when Type::Nominal then true
+        when Type::StructInstance, Type::DataInstance then !receiver.class_name.nil?
+        else false
+        end
+      end
+
+      # The three receiver-shaped block folds, in their historical order (extracted whole from
+      # `call_dispatch_type_for` for method-length budget).
+      def try_receiver_block_folds(node, receiver, arg_types)
+        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
+
+        try_hash_shape_block_fold(node, receiver)
+      end
+
+      # Issue #533 — `x.send(:selector, args)` with a LITERAL symbol is statically `x.selector(args)`:
+      # the private-boundary idiom (protobuf's `send(:get_file_descriptor)` at 84 sites) resolves through
+      # the same dispatch + project-inference tiers as the direct call would. `send` legitimately crosses
+      # visibility, so no public-only gate applies (`public_send` is treated identically — typing the
+      # success path of a call that would raise on a private method is ADR-5 optimism). Declines: a
+      # non-literal selector, a splat / forwarded tail (positional correspondence unknown), or a block at
+      # the call site (block forwarding is out of this slice).
+      LITERAL_SEND_SELECTORS = %i[send __send__ public_send].freeze
+      private_constant :LITERAL_SEND_SELECTORS
 
-        def_node, owner = resolve_user_def_with_owner(receiver.class_name, call_node.name)
+      def try_literal_send(node, receiver)
+        return nil unless LITERAL_SEND_SELECTORS.include?(node.name)
+        return nil unless node.block.nil?
+
+        args = node.arguments&.arguments
+        return nil unless args && args.first.is_a?(Prism::SymbolNode)
+
+        rest = args[1..]
+        return nil if rest.any? { |a| a.is_a?(Prism::SplatNode) || a.is_a?(Prism::ForwardingArgumentsNode) }
+
+        inner_name = args.first.unescaped.to_sym
+        inner_args = rest.map { |a| type_of(a) }
+        MethodDispatcher.dispatch(
+          receiver_type: receiver, method_name: inner_name, arg_types: inner_args,
+          block_type: nil, environment: scope.environment, call_node: node, scope: scope
+        ) ||
+          try_user_method_inference(receiver, node, inner_args, method_name: inner_name) ||
+          try_project_singleton_inference(receiver, node, inner_args, method_name: inner_name)
+      end
+
+      def try_user_method_inference(receiver, call_node, arg_types, method_name: call_node.name)
+        return nil unless user_inference_receiver?(receiver)
+
+        def_node, owner = resolve_user_def_with_owner(receiver.class_name, method_name)
         return nil if def_node.nil?
 
-        result = infer_user_method_return(def_node, receiver, arg_types)
+        result = infer_user_method_return(def_node, receiver, arg_types,
+                                          self_fold_safe: fold_safe_call_receiver?(call_node, receiver))
         return result if result.nil?
 
-        degrade_if_overridable(result, owner, call_node.name, :instance)
+        degrade_if_overridable(result, owner, method_name, :instance)
       rescue StandardError
         nil
       end
 
+      # Issue #525 — whether the RECEIVER EXPRESSION of this call is one whose struct member map is still
+      # current. Three arms:
+      #
+      # - a call that MATERIALISES the struct (`Point.new(…)`, `Point[…]`, `Struct.new(:x).new(…)`, a
+      #   `.with(…)` copy) — the object was created by this very expression, so nothing has run against it;
+      # - a local the fold-safe scan proved is never mutated / aliased / escaped;
+      # - `nil` / `self`, inheriting the CURRENT body's own grant, which is what lets a chain of
+      #   implicit-self readers propagate: `Line.new(…).outer` grants `outer`'s body `:self`, and an
+      #   `inner` call inside it carries the grant into `inner`'s body.
+      #
+      # The first arm shares `StructFolding`'s materialisation test with the direct member-read gate. Neither
+      # accepts a bare chained call: "chained" is not "fresh" once a method can hand back its own receiver,
+      # and a self-returning fluent builder is ordinary Ruby:
+      #
+      #     Line = Struct.new(:text) do
+      #       def with_text(v) = (self.text = v; self)
+      #       def shout       = text.upcase
+      #     end
+      #     Line.new("a").with_text("z").shout   # runtime "Z"
+      #
+      # Accepting the `with_text(…)` receiver as fresh would grant `shout` a member map two statements
+      # stale and fold `"A"`. Only the shapes the folding layer itself materialises qualify here.
+      #
+      # This is only a property of the receiver expression; whether the grant is actually issued also needs
+      # a `StructInstance` carrier and a body that survives the self-use scan, both decided in
+      # {#build_user_method_body_scope}.
+      def fold_safe_call_receiver?(call_node, receiver)
+        return false if call_node.nil?
+
+        case call_node.receiver
+        when Prism::CallNode then materialization_call?(call_node.receiver, receiver)
+        when Prism::LocalVariableReadNode then scope.struct_fold_safe?(call_node.receiver.name)
+        when nil, Prism::SelfNode then scope.struct_fold_safe?(:self)
+        else false
+        end
+      end
+
+      # Issue #595 — the materialisation test lives ONCE, in
+      # [`struct_materialization.rb`](method_dispatcher/struct_materialization.rb), because the direct
+      # member-read gate ({MethodDispatcher::StructFolding}`#fresh_receiver?`) needs the identical answer;
+      # see {MethodDispatcher::StructMaterialization.materialization_call?}. It resolves its own `.with`
+      # guard through `Scope`, so neither consumer supplies a lookup and neither can answer differently.
+      def materialization_call?(node, receiver)
+        MethodDispatcher::StructMaterialization.materialization_call?(node, receiver, scope)
+      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.
@@ -1347,30 +1813,53 @@ module Rigor
       # (`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)
+      # Issue #731 — resolution walks the SUPERCLASS chain, so a class method a base class defines answers
+      # on its subclasses (`class Plain < Base` with `def self.build` on `Base`: `Plain.build` was
+      # `Dynamic[top]` while `Plain.new.inst` resolved on the same fixture). Superclasses only, which is the
+      # whole shape of class-method inheritance — an `include`d module's `def self.x` is not callable on the
+      # includer, and `extend M` is already folded into the extender's own singleton entries by
+      # `ScopeIndexer`. A miss still degrades to `Dynamic[top]`, never a false resolution.
+      #
+      # The OWNER — not the receiver class — is what the overridable gate keys on, exactly as the instance
+      # side does: adopting `Base`'s literal return is unsound when a subclass redefines the method, and
+      # after this change the resolved body is routinely not the receiver's own.
+      def try_singleton_method_inference(receiver, call_node, arg_types, method_name: call_node.name)
         return nil unless receiver.is_a?(Type::Singleton)
 
-        def_node = scope.singleton_def_for(receiver.class_name, call_node.name)
+        def_node, owner = resolve_singleton_def_with_owner(receiver.class_name, method_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)
+        degrade_if_overridable(result, owner, method_name, :singleton)
       rescue StandardError
         nil
       end
 
+      # The singleton twin of {#resolve_user_def_with_owner}. Memoised in a bucket nested under the
+      # SINGLETON def table's identity as well as the class-graph trio: `class_graph_buckets` keys on
+      # `discovered_def_nodes` / `discovered_superclasses` / `discovered_includes`, and this walk reads a
+      # fourth table those three do not imply. Keying on what the answer actually depends on is the #682
+      # lesson — a memo that outlives its inputs serves one scope's answer to another.
+      def resolve_singleton_def_with_owner(class_name, method_name)
+        by_singleton = (class_graph_buckets[:singleton_def] ||= {}.compare_by_identity)
+        cache = (by_singleton[scope.discovered_singleton_def_nodes] ||= {})
+        table = (cache[class_name.to_s] ||= {})
+        key = method_name.to_sym
+        return table[key] if table.key?(key)
+
+        table[key] = scope.singleton_def_through_ancestors(class_name, method_name,
+                                                           name_memo: class_graph_buckets[:name])
+      end
+
       # The project-side singleton-method band: a `Foo.bar` call resolved against a `class << …` / `def self.…`
       # body the project itself wrote. Which of the two tiers applies is decided by the receiver carrier —
       # `Singleton[Foo]` when the constant names a class or module, `Nominal[…]` when it holds an ordinary
       # object (#320) — so the two are mutually exclusive and consulting both is one resolution attempt.
-      def try_project_singleton_inference(receiver, call_node, arg_types)
-        try_singleton_method_inference(receiver, call_node, arg_types) ||
-          try_singleton_object_constant_inference(receiver, call_node, arg_types)
+      def try_project_singleton_inference(receiver, call_node, arg_types, method_name: call_node.name)
+        try_singleton_method_inference(receiver, call_node, arg_types, method_name: method_name) ||
+          try_singleton_object_constant_inference(receiver, call_node, arg_types, method_name: method_name)
       end
 
       # #320 — resolves a call whose receiver is a constant holding an ordinary object with a `class << Const`
@@ -1378,10 +1867,10 @@ module Rigor
       # that object, so the receiver carrier is passed through unchanged. Own-constant only, and only for a
       # name the project actually recorded — a miss degrades to today's `Dynamic[top]`, never a false
       # resolution. `Singleton` receivers never reach here: {#try_singleton_method_inference} owns them.
-      def try_singleton_object_constant_inference(receiver, call_node, arg_types)
+      def try_singleton_object_constant_inference(receiver, call_node, arg_types, method_name: call_node.name)
         return nil unless receiver.is_a?(Type::Nominal)
 
-        def_node = SingletonObjectConstant.def_node_for(call_node, receiver, call_node.name, scope)
+        def_node = SingletonObjectConstant.def_node_for(call_node, receiver, method_name, scope)
         return nil if def_node.nil?
 
         infer_user_method_return(def_node, receiver, arg_types)
@@ -1396,8 +1885,6 @@ module Rigor
       # project-discovered class/module ends that branch. Cross-file: the chain is followed through
       # `Scope#discovered_superclasses` / `#discovered_includes` / `#discovered_def_nodes`, which the runner
       # seeds from the project-wide pre-pass. The walk is breadth-first, cycle-guarded, and node-count-capped.
-      ANCESTOR_WALK_LIMIT = 100
-      private_constant :ANCESTOR_WALK_LIMIT
 
       CLASS_GRAPH_CACHE_KEY = :__rigor_class_graph_cache__
       private_constant :CLASS_GRAPH_CACHE_KEY
@@ -1417,7 +1904,10 @@ module Rigor
         store = (Thread.current[CLASS_GRAPH_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] ||= { name: {}, user_def: {} }
+        # `self_pure` is issue #525's grant scan (identity-keyed by def node); it belongs here because it
+        # is a pure function of the same frozen index trio — the sibling resolver it walks reads nothing
+        # else.
+        by_super[scope.discovered_includes] ||= { name: {}, user_def: {}, self_pure: {}.compare_by_identity }
       end
 
       def resolve_user_def_through_ancestors(class_name, method_name)
@@ -1438,70 +1928,15 @@ module Rigor
         table[key] = compute_user_def_with_owner(class_name, method_name)
       end
 
+      # ADR-24 slice 2 — the walk itself lives on `Scope` ({Scope#user_def_through_ancestors}); it reads
+      # nothing but the frozen discovery index, and the `.with` guard in
+      # {MethodDispatcher::StructMaterialization} needs the SAME answer without threading dispatcher state
+      # through the dispatcher (#598 review). What stays here is the caching: the run-scoped
+      # `(class_name, method_name)` memo above, plus the per-edge name bucket handed to the walk so a class
+      # whose many methods are resolved pays each ancestor edge once.
       def compute_user_def_with_owner(class_name, method_name)
-        queue = [class_name.to_s]
-        seen = {}
-        visited = 0
-        until queue.empty?
-          current = queue.shift
-          next if current.nil? || seen[current]
-
-          seen[current] = true
-          visited += 1
-          if visited > ANCESTOR_WALK_LIMIT
-            BudgetTrace.hit(BudgetTrace::ANCESTOR_WALK_LIMIT)
-            return [nil, nil]
-          end
-
-          found = scope.user_def_for(current, method_name)
-          return [found, current] if found
-
-          enqueue_ancestors(current, queue)
-        end
-        [nil, nil]
-      end
-
-      # Pushes `current`'s direct ancestors onto the BFS queue: included / prepended modules first (Ruby
-      # places mixins nearer than the superclass), then the superclass. Each as-written name is resolved
-      # against `current`'s lexical nesting; names that resolve to no project class/module are dropped
-      # (RBS-known / third-party ancestors).
-      def enqueue_ancestors(current, queue)
-        scope.includes_of(current).each do |raw|
-          resolved = resolve_ancestor_class_name(current, raw)
-          queue.push(resolved) if resolved
-        end
-        raw_super = scope.superclass_of(current)
-        return if raw_super.nil?
-
-        resolved_super = resolve_ancestor_class_name(current, raw_super)
-        queue.push(resolved_super) if resolved_super
-      end
-
-      # Resolves a superclass name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) to a project-discovered
-      # class, following Ruby's `Module.nesting` constant lookup: try the raw name under each enclosing
-      # namespace of the subclass, innermost first, then bare. Returns nil when no candidate names a
-      # discovered user class (e.g. the superclass is an RBS-known or third-party class).
-      def resolve_ancestor_class_name(subclass_qualified, raw_superclass)
-        by_subclass = (class_graph_buckets[:name][subclass_qualified] ||= {})
-        return by_subclass[raw_superclass] if by_subclass.key?(raw_superclass)
-
-        by_subclass[raw_superclass] =
-          compute_ancestor_class_name(subclass_qualified, raw_superclass)
-      end
-
-      def compute_ancestor_class_name(subclass_qualified, raw_superclass)
-        segments = subclass_qualified.split("::")
-        (segments.length - 1).downto(0) do |i|
-          candidate = (segments[0, i] + [raw_superclass]).join("::")
-          return candidate if known_user_class?(candidate)
-        end
-        nil
-      end
-
-      def known_user_class?(name)
-        scope.discovered_superclasses.key?(name) ||
-          scope.discovered_def_nodes.key?(name) ||
-          scope.discovered_includes.key?(name)
+        scope.user_def_through_ancestors(class_name, method_name,
+                                         name_memo: class_graph_buckets[:name])
       end
 
       # ADR-57 N5 — overridable-method adoption gate. A self-call resolved to a project `def` whose owner has
@@ -1604,6 +2039,12 @@ module Rigor
       # `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.
+      # Delegates to the shared walk's edge step so this BFS and method resolution resolve ancestor names
+      # identically, sharing the per-edge memo bucket.
+      def enqueue_ancestors(current, queue)
+        scope.enqueue_ancestors(current, queue, class_graph_buckets[:name])
+      end
+
       def related_to_owner?(candidate, owner)
         queue = []
         enqueue_ancestors(candidate, queue)
@@ -1617,7 +2058,7 @@ module Rigor
 
           seen[current] = true
           visited += 1
-          return false if visited > ANCESTOR_WALK_LIMIT
+          return false if visited > Scope::ANCESTOR_WALK_LIMIT
 
           enqueue_ancestors(current, queue)
         end
@@ -1780,7 +2221,8 @@ module Rigor
       # 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
+        :receiver, :arg_types, :plain_signature, :summaries, :would_have_been_guarded,
+        :self_fold_safe
       )
       private_constant :RecursionContext
 
@@ -1801,10 +2243,16 @@ module Rigor
       RECURSION_VALUE_SIZE_CAP = 64
       private_constant :RECURSION_VALUE_SIZE_CAP
 
-      def infer_user_method_return(def_node, receiver, arg_types)
+      # `self_fold_safe` (issue #525) is the caller's statement that its RECEIVER EXPRESSION was foldable;
+      # {#build_user_method_body_scope} turns it into the body scope's `:self` sentinel when the carrier and
+      # the body both qualify. It does NOT need its own memo-key slot here — the bit is observable on the
+      # built `body_scope`, which is where every downstream consumer (the memo key, the recursion context)
+      # reads it from, so the two can never disagree.
+      def infer_user_method_return(def_node, receiver, arg_types, self_fold_safe: false)
         return nil if def_node.body.nil?
 
-        body_scope = build_user_method_body_scope(def_node, receiver, arg_types)
+        body_scope = build_user_method_body_scope(def_node, receiver, arg_types,
+                                                  self_fold_safe: self_fold_safe)
         return nil if body_scope.nil?
 
         # Recursion-guard signature. Keyed on `(receiver, method)` only — NOT the argument types. ADR-24 WD5:
@@ -1874,8 +2322,14 @@ module Rigor
       def consult_and_store_return_memo(def_node, body_scope, stack, summaries,
                                         receiver, arg_types, plain_signature)
         per_def = (return_memo_bucket[def_node] ||= {})
+        # Issue #525 — the `:self` fold-safety grant is a THIRD call-site-varying dimension: the same
+        # `(receiver, arg_types)` body returns a folded member type when the caller's receiver expression
+        # was foldable and `Dynamic[top]` when it was not. Without it in the key the first call site to
+        # reach a def would poison every later one with the other polarity. It is read off the body scope
+        # rather than passed in, so the key cannot drift from the scope that produced the result.
         memo_key = [receiver.describe(:short),
-                    arg_types.map { |type| type.describe(:short) }]
+                    arg_types.map { |type| type.describe(:short) },
+                    body_scope.struct_fold_safe?(:self)]
         if (entry = per_def[memo_key])
           BudgetTrace.hit(BudgetTrace::MEMO_HITS)
           Analysis::DependencyRecorder.replay(entry.read_set) if Analysis::DependencyRecorder.active?
@@ -1977,7 +2431,11 @@ module Rigor
 
         context = RecursionContext.new(
           receiver: receiver, arg_types: arg_types, plain_signature: plain_signature,
-          summaries: summaries, would_have_been_guarded: would_have_been_guarded
+          summaries: summaries, would_have_been_guarded: would_have_been_guarded,
+          # Issue #525 — read off the built scope so the bot-collapse retry rebuilds a widened scope with
+          # the SAME `:self` polarity the first attempt used; a retry that silently dropped the grant would
+          # return a different type for the same call.
+          self_fold_safe: body_scope.struct_fold_safe?(:self)
         )
         evaluate_guarded_user_method_body(def_node, body_scope, stack, signature, context)
       end
@@ -2222,9 +2680,9 @@ module Rigor
       # `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)
+      def widened_user_method_body_scope(def_node, receiver, arg_types, self_fold_safe: false)
         widened_args = arg_types.map { |arg_type| widen_value_pinned(arg_type) }
-        build_user_method_body_scope(def_node, receiver, widened_args)
+        build_user_method_body_scope(def_node, receiver, widened_args, self_fold_safe: self_fold_safe)
       end
 
       # ADR-55 slice 2 bot-collapse resolution (2026-06-11). Called when a fixpoint iteration computed `bot`
@@ -2244,7 +2702,8 @@ module Rigor
       # 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)
+          widened_scope = widened_user_method_body_scope(def_node, context.receiver, context.arg_types,
+                                                         self_fold_safe: context.self_fold_safe)
           return fixpoint_user_method_return(def_node, widened_scope, context, widened: true) unless widened_scope.nil?
         end
 
@@ -2382,20 +2841,23 @@ module Rigor
 
       # Builds the body scope for a user-defined instance method call: a fresh `Scope` with `self_type` set
       # to the receiver's nominal type, the project-wide accumulators inherited (so the body sees the same
-      # `discovered_classes` / `class_ivars` / etc. the caller does), and required positional parameters
-      # bound from the call's `arg_types` by index. Returns nil when the parameter shape is too complex for
-      # the first-iteration binder (rest args, keyword args, block params, etc.).
-      def build_user_method_body_scope(def_node, receiver, arg_types)
+      # `discovered_classes` / `class_ivars` / etc. the caller does), and the call's `arg_types` bound to
+      # the parameters. Returns nil when the binding is truly ambiguous (arity mismatch, trailing `post`
+      # params, `...` forwarding).
+      #
+      # Issue #524 — the binder is per-PARAMETER, not per-signature. The first iteration declined any def
+      # with an optional / rest / keyword / block parameter outright, so ONE `options = {}` default zeroed
+      # out an otherwise-inferable return at every call site (the widest engine lever the 2026-09-01 sweep
+      # measured, verified on ten targets). Now: requireds bind by index; supplied optionals by index and
+      # unsupplied ones from a LITERAL default (else `Dynamic`); `*rest` collects the leftover positionals
+      # as a Tuple; keywords bind by name from a trailing keyword-hash shape, falling back to their literal
+      # default — or `Dynamic` when the shape is open or absent; `**kwrest`, `&block`, and destructured
+      # positionals bind `Dynamic`. Binding `Dynamic` is monotone-safe (wider in → wider out), so the only
+      # declines left are the shapes where positional CORRESPONDENCE itself is unknowable.
+      def build_user_method_body_scope(def_node, receiver, arg_types, self_fold_safe: false)
         params = def_node.parameters
-        required = params&.requireds || []
-        return nil unless params.nil? || user_method_param_shape_simple?(params)
-        return nil unless required.size == arg_types.size
-
-        # Bind required positionals by index. The body scope starts from an empty fact store and narrowing
-        # set, so `with_local`'s fact / narrowing invalidations would be no-ops here — build the locals
-        # table directly (matching `with_local`'s `name.to_sym` key).
-        locals = {}
-        required.each_with_index { |param, index| locals[param.name.to_sym] = arg_types[index] }
+        locals = bind_params_from_call_types(params, arg_types)
+        return nil if locals.nil?
 
         # Construct the body scope in a SINGLE allocation — the previous `Scope.empty.with_*.with_*…` chain
         # allocated a fresh frozen Scope per field, run per user-method-call inference (ADR-44). The
@@ -2405,12 +2867,179 @@ module Rigor
           environment: scope.environment,
           locals: locals.freeze,
           self_type: receiver,
+          # Issue #681 — the chain the walk recorded as it entered `def_node`'s own declaration. Without it
+          # this scope carried a self type alone, and `Reflection.lexical_nesting_chain` fell back to peeling
+          # `receiver`'s qualified name — which cannot tell a compact `class Admin::Maker` from the nested
+          # spelling, and for an INHERITED body peels the subclass rather than the declaration that owns it.
+          # The same `Post.new` then typed one way on the line that writes it and another through this
+          # re-walk. Issue #716 — `[]` for a top-level def: that IS Ruby's `Module.nesting` there, and it
+          # sends the body's constants to the top level instead of to the caller's namespace.
+          lexical_nesting: recorded_def_nesting(def_node),
           discovery: scope.discovery,
-          struct_fold_safe_locals: struct_fold_safe_locals_for(def_node.body),
+          struct_fold_safe_locals: body_fold_safe_locals(def_node, receiver, self_fold_safe),
           dynamic_origins: scope.dynamic_origins
         )
       end
 
+      # Issue #681 / #707 — the ONE place in `lib/` that answers "what `Module.nesting` was recorded for this
+      # def node". `Scope::DiscoveryIndex#discovered_def_nestings` is the owner; the resolver memo is that
+      # table's REHYDRATION for the one population it cannot hold — a def served from an ADR-85 seed bundle,
+      # whose node {Inference::DefNodeResolver} mints from its own parse, so no table keyed by the identities
+      # the analyzer's own walks produce can contain it.
+      #
+      # The order is safe on OBJECT PROVENANCE, not on any file-level split: the resolver parses separately
+      # and both tables are `compare_by_identity`, so no node is a key in both, and the content-digest gate
+      # makes the two agree where they answer for the same def through different objects. A file can be
+      # bundle-served and walked live in the SAME run (an unchanged file re-analysed as a dependent), which is
+      # exactly why the guarantee has to rest on the parse rather than on the file — see
+      # {Inference::DefNodeResolver.rehydrated_nesting}. Routing both through one reader is what keeps a cold
+      # run and an `--incremental` recheck answering the same constant for the same body; the rehydration half
+      # is populated only inside `DefNodeResolver.with_run`, and outside it this falls back to the peel.
+      def recorded_def_nesting(def_node)
+        scope.discovery.discovered_def_nestings[def_node] || DefNodeResolver.rehydrated_nesting(def_node)
+      end
+
+      # The body scope's fold-safe set: the body's own struct locals, plus issue #525's `:self` sentinel
+      # when the caller's receiver expression was foldable AND the carrier is a `StructInstance` AND the
+      # body's every use of `self` is a pure read (no member setter, no escape, no unrecognised self-call —
+      # see {Inference::StructFoldSafety.self_fold_safe_body?}). All three are required: the first is the
+      # caller's evidence that the map is current on entry, the last two that the body keeps it current.
+      def body_fold_safe_locals(def_node, receiver, self_fold_safe)
+        locals = struct_fold_safe_locals_for(def_node.body)
+        return locals unless self_fold_safe && receiver.is_a?(Type::StructInstance)
+        return locals unless self_fold_safe_grant?(def_node, receiver)
+
+        locals + [:self]
+      end
+
+      # The memoised entry point to the grant scan. Without the memo the walk re-runs on every
+      # granted-CANDIDATE call, return-memo HITS included — the body scope is built before the memo is
+      # consulted, so a hot call site pays the scan every time. Only the OUTERMOST scan is memoised: an
+      # inner answer can rest on the cycle guard's `seen` set, which is not part of the key.
+      def self_fold_safe_grant?(def_node, receiver)
+        per_def = (class_graph_buckets[:self_pure][def_node] ||= {})
+        key = [receiver.class_name, receiver.member_names]
+        return per_def[key] if per_def.key?(key)
+
+        per_def[key] = self_fold_safe_body?(def_node.body, receiver, [def_node])
+      end
+
+      # Whether `body`'s every use of `self` is a pure read, resolving each unrecognised self-call against
+      # the receiver's own class so a body that DELEGATES can still hold the grant: `def outer; shout; end`
+      # keeps it because `shout` reads a member, while `def go; reset!; text; end` loses it because `reset!`
+      # writes one. `seen` breaks a mutual-call cycle by refusing (the conservative direction) and
+      # `SELF_PURE_DEPTH` bounds the walk — an unresolvable name (`puts`, `raise`, a method from an RBS-only
+      # ancestor) refuses too, so every answer this returns is backed by a body actually examined.
+      SELF_PURE_DEPTH = 4
+      private_constant :SELF_PURE_DEPTH
+
+      def self_fold_safe_body?(body, receiver, seen)
+        StructFoldSafety.self_fold_safe_body?(body, receiver.member_names) do |name|
+          next false if seen.size > SELF_PURE_DEPTH
+
+          sibling, = resolve_user_def_with_owner(receiver.class_name, name)
+          next false if sibling.nil? || sibling.body.nil? || seen.include?(sibling)
+
+          self_fold_safe_body?(sibling.body, receiver, seen + [sibling])
+        end
+      end
+
+      # The locals table for the body scope, or nil to decline. Keys match `with_local`'s `name.to_sym`.
+      # The body scope starts from an empty fact store and narrowing set, so `with_local`'s fact /
+      # narrowing invalidations would be no-ops here — the table is built directly.
+      def bind_params_from_call_types(params, arg_types)
+        return arg_types.empty? ? {} : nil if params.nil?
+        return nil unless bindable_param_shape?(params)
+
+        positional = arg_types.dup
+        kw_shape = positional.pop if takes_keywords?(params) && positional.last.is_a?(Type::HashShape)
+        locals = bind_positional_params(params, positional)
+        return nil if locals.nil?
+
+        bind_keyword_params(params, kw_shape, locals)
+        locals[params.keyword_rest.name.to_sym] = dynamic_top if params.keyword_rest&.name
+        locals[params.block.name.to_sym] = dynamic_top if params.block&.name
+        locals
+      end
+
+      # Trailing required positionals after a rest (`def f(a, *m, z)`) shift the correspondence; `...`
+      # arrives as the keyword_rest slot. Both stay declined — correspondence, not width, is the issue.
+      def bindable_param_shape?(params)
+        params.is_a?(Prism::ParametersNode) &&
+          params.posts.empty? &&
+          !params.keyword_rest.is_a?(Prism::ForwardingParameterNode)
+      end
+
+      def takes_keywords?(params)
+        params.keywords.any? || !params.keyword_rest.nil?
+      end
+
+      def bind_positional_params(params, positional)
+        requireds = params.requireds
+        optionals = params.optionals
+        return nil if positional.size < requireds.size
+        return nil if params.rest.nil? && positional.size > requireds.size + optionals.size
+
+        locals = {}
+        requireds.each_with_index { |param, index| bind_positional_param(locals, param, positional[index]) }
+        optionals.each_with_index do |param, index|
+          supplied = positional[requireds.size + index]
+          locals[param.name.to_sym] = supplied || literal_default_type(param.value)
+        end
+        bind_rest_param(params, positional, locals)
+        locals
+      end
+
+      def bind_rest_param(params, positional, locals)
+        rest_name = params.rest&.name
+        return if rest_name.nil?
+
+        leftover = positional[(params.requireds.size + params.optionals.size)..] || []
+        locals[rest_name.to_sym] = Type::Combinator.tuple_of(*leftover)
+      end
+
+      # A destructured positional (`def f((a, b))`) consumes one argument slot but binds its leaf names
+      # `Dynamic` — element correspondence through the destructure is a later slice.
+      def bind_positional_param(locals, param, arg_type)
+        if param.is_a?(Prism::MultiTargetNode)
+          Destructure.target_names(param).each { |name| locals[name.to_sym] = dynamic_top }
+        else
+          locals[param.name.to_sym] = arg_type
+        end
+      end
+
+      def bind_keyword_params(params, kw_shape, locals)
+        open_shape = kw_shape && kw_shape.extra_keys == :open
+        params.keywords.each do |param|
+          name = param.name.to_s.delete_suffix(":").to_sym
+          supplied = kw_shape&.pairs&.[](name)
+          locals[name] = supplied ||
+                         (open_shape ? dynamic_top : keyword_default_type(param))
+        end
+      end
+
+      def keyword_default_type(param)
+        param.respond_to?(:value) && param.value ? literal_default_type(param.value) : dynamic_top
+      end
+
+      # A default expression contributes its type only when it is lexically scope-free — a scalar literal
+      # or an EMPTY collection literal (`options = {}` is the dominant Rails idiom). Anything that could
+      # read the def's own lexical scope binds `Dynamic` instead of being mis-typed in the caller's scope.
+      LITERAL_DEFAULT_NODES = [
+        Prism::IntegerNode, Prism::FloatNode, Prism::StringNode, Prism::SymbolNode,
+        Prism::TrueNode, Prism::FalseNode, Prism::NilNode
+      ].freeze
+      private_constant :LITERAL_DEFAULT_NODES
+
+      def literal_default_type(value_node)
+        return dynamic_top if value_node.nil?
+        return type_of(value_node) if LITERAL_DEFAULT_NODES.any? { |klass| value_node.is_a?(klass) }
+        return type_of(value_node) if value_node.is_a?(Prism::ArrayNode) && value_node.elements.empty?
+        return type_of(value_node) if value_node.is_a?(Prism::HashNode) && value_node.elements.empty?
+
+        dynamic_top
+      end
+
       # ADR-48 Struct slice 3 — the fold-safe-local set for a method body (runs only on a return-memo miss,
       # so the per-call cost is bounded — measured perf-neutral). Struct member layouts of constant
       # receivers are resolved through the discovery side-table the body scope inherits.
@@ -2421,19 +3050,6 @@ module Rigor
         )
       end
 
-      # First iteration accepts only required positional parameters: `def foo(a, b, c)`. Optionals, rest,
-      # keyword params, and block params disqualify the method from inference (the caller observes
-      # `Dynamic[Top]` instead).
-      def user_method_param_shape_simple?(params)
-        return false unless params.is_a?(Prism::ParametersNode)
-
-        params.optionals.empty? &&
-          params.rest.nil? &&
-          params.keywords.empty? &&
-          params.keyword_rest.nil? &&
-          params.block.nil?
-      end
-
       # Slice A-engine. Implicit-self calls (no `node.receiver`) adopt the surrounding scope's `self_type`
       # as their receiver so calls like `attr_reader_method_name` or `private_helper(...)` inside an
       # instance method dispatch against the enclosing class. Slice 7 phase 10 — when `self_type` is nil
@@ -2533,11 +3149,187 @@ module Rigor
         result || dynamic_top
       end
 
+      # The block body's value type — what the dispatcher binds a generic block-return variable to.
+      #
+      # Issue #533 item 9: this pass used to type only the body's LAST statement, in the block's ENTRY scope.
+      # A tail reading a name an earlier statement of the same body binds (`m.synchronize do v = 42; v end`)
+      # therefore never saw the binding and fell through `local_read` to `Dynamic[top]`, while the main pass
+      # — which threads scope statement by statement through `StatementEvaluator` — held `42` for the very
+      # same node. {#threaded_block_body_type} closes that gap by reusing the main pass's evaluator; a decline
+      # keeps the tail-only answer verbatim.
       def type_block_body(block_node, block_scope)
         body = block_node.body
         return Type::Combinator.constant_of(nil) if body.nil?
 
-        block_scope.type_of(body)
+        threaded_block_body_type(body, block_scope) || block_scope.type_of(body)
+      end
+
+      # Re-typing the whole body would be wrong to do unconditionally: this path runs for EVERY block-bearing
+      # call, and the statements ahead of the tail are pure cost whenever the tail does not depend on them.
+      # Three declines keep that cost where the defect actually is, each falling back to the tail-only path:
+      #
+      # - a `nil` or non-`StatementsNode` body (`do … rescue … end` parses as a `BeginNode`) and a
+      #   single-statement body — the overwhelming majority of blocks — pay nothing at all;
+      # - a multi-statement body pays one DFS over its non-tail statements, and threads only when the tail
+      #   READS a variable name one of them WRITES or MUTATES IN PLACE ({#tail_depends_on_body_binding?}).
+      #   That is exactly the diagnosed shape, so a block whose tail does not consume the body's own
+      #   bindings keeps today's type;
+      # - the fold is not re-entrant. `StatementEvaluator#eval_call` already evaluates each nested block body
+      #   once, plus up to three more times under the ADR-56 `BodyFixpoint` when the block rebinds a captured
+      #   local, so a fold nested inside a fold would multiply that work per block-nesting level. Inside a
+      #   threaded body a nested block-bearing call reverts to the tail-only path — a wider answer in a rare
+      #   shape, never a new false positive.
+      #
+      # ADR-56 interaction: the fold cannot double-apply or fight the captured-local write-back. That
+      # write-back is `StatementEvaluator#write_back_block_captures`, computed from the CALLER's scope into
+      # the caller's continuation; this pass only derives a value type from a throwaway block scope and
+      # discards the exit scope, exactly as the tail-only path did.
+      #
+      # Any failure inside the fold falls back to the tail-only answer rather than propagating: the enclosing
+      # `block_return_type_for` rescue would otherwise report "no block" to the dispatcher, which is a much
+      # larger regression than a wide block return.
+      def threaded_block_body_type(body, block_scope)
+        return nil unless body.is_a?(Prism::StatementsNode)
+
+        statements = body.body
+        return nil if statements.size < 2
+        return nil if block_body_threading_suppressed?
+        return nil unless tail_depends_on_body_binding?(statements)
+
+        without_block_body_threading { block_scope.evaluate(body).first }
+      rescue StandardError
+        nil
+      end
+
+      # Suppression flag for {#threaded_block_body_type} — set while a fold is running (so a fold never nests)
+      # and while the per-element Tuple fold is over its arity cap. Thread-local because block typing is
+      # re-entrant within one thread and the fork-pool workers each own their own.
+      THREADED_BLOCK_BODY_KEY = :__rigor_threaded_block_body__
+      private_constant :THREADED_BLOCK_BODY_KEY
+
+      def block_body_threading_suppressed?
+        Thread.current[THREADED_BLOCK_BODY_KEY] ? true : false
+      end
+
+      # Runs the block with the scope-threading fold suppressed, restoring the previous state (not clearing
+      # it) on the way out, so nesting a suppressed region inside another cannot re-enable threading.
+      def without_block_body_threading
+        previous = Thread.current[THREADED_BLOCK_BODY_KEY]
+        Thread.current[THREADED_BLOCK_BODY_KEY] = true
+        begin
+          yield
+        ensure
+          Thread.current[THREADED_BLOCK_BODY_KEY] = previous
+        end
+      end
+
+      # Every variable-write form whose name `StatementEvaluator` threads into the following statement's
+      # scope, including the multi-assign / pattern targets that appear under a `MultiWriteNode`.
+      VARIABLE_WRITE_NODES = Set[
+        Prism::LocalVariableWriteNode, Prism::LocalVariableOperatorWriteNode,
+        Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode,
+        Prism::LocalVariableTargetNode,
+        Prism::InstanceVariableWriteNode, Prism::InstanceVariableOperatorWriteNode,
+        Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableAndWriteNode,
+        Prism::InstanceVariableTargetNode,
+        Prism::ClassVariableWriteNode, Prism::ClassVariableOperatorWriteNode,
+        Prism::ClassVariableOrWriteNode, Prism::ClassVariableAndWriteNode,
+        Prism::ClassVariableTargetNode,
+        Prism::GlobalVariableWriteNode, Prism::GlobalVariableOperatorWriteNode,
+        Prism::GlobalVariableOrWriteNode, Prism::GlobalVariableAndWriteNode,
+        Prism::GlobalVariableTargetNode
+      ].freeze
+      private_constant :VARIABLE_WRITE_NODES
+
+      # Every node that OBSERVES a variable binding: the plain reads plus the compound writes, which read
+      # their target before rebinding it (`v += 1` in the tail depends on an earlier `v = 0`).
+      VARIABLE_READ_NODES = (
+        VARIABLE_WRITE_NODES | [
+          Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode,
+          Prism::ClassVariableReadNode, Prism::GlobalVariableReadNode
+        ]
+      ).freeze
+      private_constant :VARIABLE_READ_NODES
+
+      # A `next` / `break` that leaves THIS block carries a value the fold cannot see: `evaluate(body).first`
+      # is the fall-through value only, and no next-value join into the block return exists (`type_of_jump`
+      # types both as `Bot`). So `m.synchronize do next 5 if flag; v = 42; v end` really can answer 5 at
+      # runtime, and threading would type it `42`. Both forms escape with a value — `next v` is the block's
+      # value for that yield, `break v` is the yielding CALL's value — so both must decline.
+      JUMP_NODES = Set[Prism::NextNode, Prism::BreakNode].freeze
+      private_constant :JUMP_NODES
+
+      # Constructs that RETARGET a `next` / `break` nested inside them, so a jump below one of these says
+      # nothing about our block's value and must not trigger the decline. A nested `BlockNode` / `LambdaNode`
+      # is the jump's own block (`do xs.each { next 1 }; v = 42; v end` threads soundly — the inner `next`
+      # ends the inner iteration); a loop consumes both forms (`while … next 5 … end` continues the loop);
+      # a `DefNode` body is a different method entirely.
+      JUMP_BOUNDARY_NODES = Set[
+        Prism::BlockNode, Prism::LambdaNode, Prism::DefNode,
+        Prism::WhileNode, Prism::UntilNode, Prism::ForNode
+      ].freeze
+      private_constant :JUMP_BOUNDARY_NODES
+
+      # True when the tail statement observes a variable name one of the earlier statements binds OR mutates
+      # in place — the two ways threading the scope through the body can change the tail's type — AND no
+      # earlier statement can jump out of the block with a value. The name sets are compared sigil-and-all
+      # across kinds, so the answer over-approximates (an `@x` write plus an `x` read threads needlessly);
+      # over-approximating only spends the fold, it never changes an answer.
+      #
+      # The in-place half is issue #587. `outer = []; m.synchronize do outer.push(1); outer end` binds no
+      # variable in its prefix — `push` is a call, not a write node — so a write-only scan declined and the
+      # tail kept the entry scope's empty `Tuple[]`, a wrong-precise answer (the runtime value is `[1]`) that
+      # hands downstream rules a provably-empty array. Threading is the fix, not a cost: `StatementEvaluator`
+      # runs `MutationWidening.widen_after_call` on the `push`, so the threaded tail reads the widened
+      # `Array[…]`. A call therefore contributes every variable its receiver can evaluate to
+      # ({ReceiverAlias.candidates} — the ternary-selected receiver of issue #277 included) whenever its name
+      # is one the widening responds to ({MutationWidening::SHAPE_MUTATORS}); keying on the widening's own
+      # tables is what keeps "the scan says thread" and "threading changes something" the same predicate.
+      #
+      # Cost is two walks of the body, the second only when the first found a write and no jump — the same
+      # order of cost `StatementEvaluator`'s own per-call captured-write scan already pays, and far below
+      # re-typing. The prefix walk is hand-rolled rather than `Source::NodeWalker.each` because the two
+      # questions it answers have different depths: a write is collected at ANY depth (a block is a closure,
+      # so `[1].each { v = 5 }` really does bind the outer `v`, and `[1].each { outer << 1 }` really does
+      # mutate the outer `outer`), while a jump counts only above the nearest {JUMP_BOUNDARY_NODES} boundary.
+      def tail_depends_on_body_binding?(statements)
+        written = Set.new
+        statements[0...-1].each do |statement|
+          return false unless prefix_statement_jump_free?(statement, written, false)
+        end
+        return false if written.empty?
+
+        Source::NodeWalker.each(statements.last) do |node|
+          return true if VARIABLE_READ_NODES.include?(node.class) && written.include?(node.name)
+        end
+        false
+      end
+
+      # True when `node` cannot jump out of the block with a value, collecting into `written` the names it
+      # binds (a variable-write node) or mutates in place (a {MutationWidening::SHAPE_MUTATORS} call, through
+      # every variable its receiver can evaluate to) on the way down. `retargeted` is true once the descent
+      # has passed a boundary.
+      #
+      # A `Prism::DefinedNode`'s operand is never evaluated, so it is not descended into — the same rule
+      # {Source::NodeWalker} applies, for the same reason: neither a write nor a jump under `defined?` runs.
+      def prefix_statement_jump_free?(node, written, retargeted)
+        return false if !retargeted && JUMP_NODES.include?(node.class)
+
+        written << node.name if VARIABLE_WRITE_NODES.include?(node.class)
+        collect_mutated_receivers(node, written) if node.is_a?(Prism::CallNode)
+        return true if node.is_a?(Prism::DefinedNode)
+
+        child_retargeted = retargeted || JUMP_BOUNDARY_NODES.include?(node.class)
+        node.rigor_each_child do |child|
+          return false unless prefix_statement_jump_free?(child, written, child_retargeted)
+        end
+        true
+      end
+
+      def collect_mutated_receivers(call_node, written)
+        return unless MutationWidening::SHAPE_MUTATORS.include?(call_node.name)
+
+        ReceiverAlias.candidates(call_node.receiver).each { |read| written << read.name }
       end
 
       # v0.0.6 phase 2 — per-element block fold for Tuple receivers under `:map` / `:collect`. Walks every
@@ -2589,15 +3381,100 @@ module Rigor
       #   dispatched as a zero-arg method on each element type.
       #
       # Any other shape (`&proc_local`, `&method(:foo)`, no block) returns `nil` so the fold declines.
+      # Arity cap on the scope-threading fold under this per-element walk. The `Constant<Range>` receivers are
+      # already capped at {PER_ELEMENT_RANGE_LIMIT} positions, but a Tuple's elements come through
+      # {#per_element_elements_of} uncapped — a 40-element array literal is 40 positions, and each one that
+      # threads pays a FULL body evaluation rather than the tail-only typing this walk used to cost. Above the
+      # cap the walk still runs (the fold's own per-position precision is unchanged); only the threading is
+      # suppressed, so a body whose tail reads a body-local answers `Dynamic[top]` at every position instead
+      # of its value. That is the cliff: `[1, …, 8].map do v = e; v end` folds to the values and a ninth
+      # element drops the whole result to `Dynamic[top]` positions. It is set at the Range path's limit so one
+      # number governs both receivers.
+      PER_ELEMENT_THREADING_LIMIT = PER_ELEMENT_RANGE_LIMIT
+      private_constant :PER_ELEMENT_THREADING_LIMIT
+
       def per_element_block_results(block, element_types)
         case block
         when Prism::BlockNode
-          element_types.map { |element_type| type_block_body_with_param(block, [element_type]) }
+          per_element_body_results(block, element_types)
         when Prism::BlockArgumentNode
           per_element_symbol_results(block, element_types)
         end
       end
 
+      def per_element_body_results(block, element_types)
+        captured = per_element_captured_bindings(block, element_types)
+        results = lambda do
+          element_types.map { |element_type| type_block_body_with_param(block, [element_type], captured: captured) }
+        end
+        return results.call if element_types.size <= PER_ELEMENT_THREADING_LIMIT
+
+        without_block_body_threading(&results)
+      end
+
+      # Issue #587 (b) — first-iteration pinning. Every position of this fold is typed from the SAME entry
+      # scope, so a body that rebinds a captured outer local answers the FIRST iteration's value at every
+      # position: `total = 0; [1, 2].map do total += 1; total end` folded to `[1, 1]` (runtime `[1, 2]`), and
+      # `r.first == 1` then folded to `true` — a live always-truthy on correct code. The ADR-56 fixpoint
+      # (`StatementEvaluator#write_back_block_captures`) already computes the honest binding of such a local
+      # — the join over the pre-call binding and every permitted iteration, value-pin widened, floored to
+      # `Dynamic[top]` on structural compounding (`x = [x]`) — but it runs AFTER the call is typed and feeds
+      # only the continuation. This fold runs the same `BodyFixpoint` over the same name set
+      # ({CapturedLocals.writes}) up front and binds each such local to its converged type in every
+      # position's entry scope, so a position answers what the local can be in ANY iteration
+      # (`[Integer, Integer]`), never what it was in the first.
+      #
+      # Only the rebound names move. A position whose tail reads an untouched captured local or a block-local
+      # keeps its exact fold (`[5, 5]`, `[42, 42]`), and a predicate that ignores the rebound counter still
+      # decides (`select do seen += 1; e > 1 end` still folds to `[2]`); a blanket decline would have lost all
+      # three for nothing. The fixpoint binds the block parameter to the union of the elements, so its cost
+      # is independent of the arity — which is why the per-element threading cap is NOT a reason to floor: a
+      # ninth element keeps `Integer` where it would otherwise keep the stale `0`.
+      #
+      # Under threading suppression — this fold nested inside another threaded body — the fixpoint's body
+      # evaluations are exactly the re-entrant cost the suppression exists to refuse, so the names take the
+      # escaping-block floor (`Dynamic[top]`) instead: cheaper, wider, still sound. A failure inside the
+      # fixpoint takes the same floor rather than the seed — a seed that reaches a position is the pin this
+      # exists to remove.
+      #
+      # Returns `nil` (no binding to apply) for the overwhelmingly common body that rebinds nothing captured.
+      def per_element_captured_bindings(block, element_types)
+        names = CapturedLocals.writes(block, scope)
+        return nil if names.empty?
+        return captured_floor(names) if block_body_threading_suppressed?
+
+        begin
+          converged_captured_bindings(block, names, element_types)
+        rescue StandardError
+          captured_floor(names)
+        end
+      end
+
+      def captured_floor(names)
+        names.to_h { |name| [name, Type::Combinator.untyped] }
+      end
+
+      def converged_captured_bindings(block, names, element_types)
+        param_types = [Type::Combinator.union(*element_types)]
+        BodyFixpoint.converge(
+          names: names,
+          seed_bindings: names.to_h { |name| [name, scope.local(name)] },
+          widen: Type::Combinator.method(:widen_value_pinned),
+          evaluate_body: ->(bindings) { captured_exit_bindings(block, param_types, bindings, names) }
+        )
+      end
+
+      # One fixpoint pass: the body evaluated from `bindings` with the block parameters bound over them (the
+      # same layering as {#type_block_body_with_param}), returning the per-name exit binding. Threading is
+      # suppressed for the pass, as it is for every full body evaluation the block-return pass runs.
+      def captured_exit_bindings(block, param_types, bindings, names)
+        params = BlockParameterBinder.new(expected_param_types: param_types).bind(block)
+        entry = bindings.reduce(scope) { |acc, (name, type)| acc.with_local(name, type) }
+        entry = params.reduce(entry) { |acc, (name, type)| acc.with_local(name, type) }
+        _type, exit_scope = without_block_body_threading { entry.evaluate(block.body) }
+        names.to_h { |name| [name, exit_scope.local(name)] }
+      end
+
       def per_element_symbol_results(block_arg, element_types)
         expression = block_arg.expression
         return nil unless expression.is_a?(Prism::SymbolNode)
@@ -3006,14 +3883,16 @@ module Rigor
         end
       end
 
-      def type_block_body_with_param(block_node, expected_param_types)
+      # `captured:` — issue #587 (b): the per-name entry binding of every captured outer local the body rebinds
+      # ({#per_element_captured_bindings}), laid under the parameter bindings so a parameter still shadows.
+      def type_block_body_with_param(block_node, expected_param_types, captured: nil)
         bindings = BlockParameterBinder.new(expected_param_types: expected_param_types).bind(block_node)
-        block_scope = bindings.reduce(scope) { |acc, (name, type)| acc.with_local(name, type) }
+        block_scope = (captured || {}).reduce(scope) { |acc, (name, type)| acc.with_local(name, type) }
+        block_scope = bindings.reduce(block_scope) { |acc, (name, type)| acc.with_local(name, type) }
         type_block_body(block_node, block_scope)
       rescue StandardError
         nil
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end