rigortype 0.3.5 → 0.3.7

data/lib/rigor/inference/statement_evaluator.rb

@@ -11,17 +11,21 @@ require_relative "../source/constant_path"
 require_relative "anonymous_meta_class"
 require_relative "block_parameter_binder"
 require_relative "body_fixpoint"
+require_relative "captured_locals"
 require_relative "dynamic_origin"
 require_relative "../analysis/check_rules/inferred_param_guard"
 require_relative "struct_fold_safety"
 require_relative "closure_escape_analyzer"
+require_relative "content_join"
 require_relative "indexed_narrowing"
+require_relative "index_write_widening"
 require_relative "method_dispatcher"
 require_relative "method_parameter_binder"
 require_relative "multi_target_binder"
 require_relative "mutation_widening"
 require_relative "narrowing"
 require_relative "optimistic_origin"
+require_relative "version_guard"
 
 module Rigor
   module Inference
@@ -52,7 +56,7 @@ module Rigor
     #
     # See docs/internal-spec/inference-engine.md for the public contract and docs/adr/4-type-inference-engine.md for the
     # slice rationale.
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class StatementEvaluator
       # Hash-based dispatch keeps `evaluate` linear and lets future slices add control-flow node kinds without growing a
       # single case statement past RuboCop's cyclomatic budget. Anonymous Prism subclasses are not expected.
@@ -76,7 +80,11 @@ module Rigor
         Prism::GlobalVariableAndWriteNode => :eval_global_and_write,
         Prism::GlobalVariableOperatorWriteNode => :eval_global_operator_write,
         Prism::IndexOrWriteNode => :eval_index_or_write,
+        Prism::IndexAndWriteNode => :eval_index_write,
+        Prism::IndexOperatorWriteNode => :eval_index_write,
         Prism::MultiWriteNode => :eval_multi_write,
+        Prism::ConstantWriteNode => :eval_constant_write,
+        Prism::ConstantPathWriteNode => :eval_constant_write,
         Prism::IfNode => :eval_if,
         Prism::UnlessNode => :eval_unless,
         Prism::ElseNode => :eval_else,
@@ -128,6 +136,15 @@ module Rigor
       # singleton-method RBS lookups.
       ClassFrame = Data.define(:name, :singleton)
 
+      # Issue #652 — Ruby's `Module.nesting` for the body currently being evaluated, innermost first, built as
+      # the walk ENTERS each declaration rather than reconstructed from the qualified name afterwards. A
+      # compact `module A::B` contributes ONE entry, the nested `module A; module B` two, and both render the
+      # same `class_name`, so the distinction survives only if it is recorded here. `[]` is the file top level,
+      # and nothing is stamped for it — a scope with no recorded chain falls back to the name-peel, which
+      # answers the same thing at the top level and answers correctly for a body this walk never entered.
+      EMPTY_NESTING = [].freeze
+      private_constant :EMPTY_NESTING
+
       # @param scope [Rigor::Scope]
       # @param tracer [Rigor::Inference::FallbackTracer, nil]
       # @param on_enter [#call, nil] optional `(node, scope) ->` callable
@@ -150,11 +167,12 @@ module Rigor
       #   `Integer`). Display-path only — `rigor check` leaves it off,
       #   keeping its diagnostics and wall-clock unchanged.
       def initialize(scope:, tracer: nil, on_enter: nil, class_context: [].freeze,
-                     converged_loop_recording: false)
+                     lexical_nesting: EMPTY_NESTING, converged_loop_recording: false)
         @scope = scope
         @tracer = tracer
         @on_enter = on_enter
         @class_context = class_context.freeze
+        @lexical_nesting = lexical_nesting.freeze
         @converged_loop_recording = converged_loop_recording
       end
 
@@ -309,6 +327,48 @@ module Rigor
         [rhs_type, post_rhs.with_global(node.name, rhs_type)]
       end
 
+      # `Const = rvalue` / `A::Const = rvalue`. The pair is exactly what the default expression path produced before
+      # this handler existed — the expression typer types the rvalue and the scope comes back unchanged, a constant
+      # write binding no local — plus one walk the default path could not make. Issue #590: when the rvalue is a
+      # class-creating meta call with a literal block (`Const = Struct.new(:text) do … end` and its `Data.define` /
+      # `Class.new` / `Module.new` twins) the block is a CLASS BODY, `class_eval`'d on the class the call creates,
+      # and it is entered as one here — the constant-write counterpart of {#evaluate_block_if_present}'s #319 arm.
+      # Left to the default path the body was never walked at all, so `ScopeIndexer.propagate` handed every node
+      # inside the ENCLOSING scope: at file top level a nil `self_type`, which made `Scope#toplevel?` hold inside
+      # every `def` of the body and `call.unresolved-toplevel` fire on the struct's own member reads (and on
+      # `attr_reader`, the very macro #319 silenced at every other position); inside a module, the module's own
+      # `self` — a wrong receiver for every implicit-self call in the body.
+      def eval_constant_write(node)
+        result = [scope.type_of(node, tracer: tracer), scope]
+        context = meta_new_constant_body_context(node)
+        return result if context.nil?
+
+        call_node = node.value
+        enter_meta_class_body(call_node.block, build_block_entry_scope(call_node, call_node.block), context)
+        result
+      end
+
+      # The class context a meta-new rvalue block is entered under, or nil when the rvalue is not that shape. The
+      # KEY must be the one `ScopeIndexer` filed the body's defs and member layout under, so the two passes agree —
+      # which is why the decision is delegated to the ScopeIndexer's own recognition rather than re-spelled here. A
+      # `Prism::ConstantWriteNode` whose rvalue `ScopeIndexer.meta_new_block_body` recognises is keyed by the
+      # constant's qualified name, one frame appended to the lexical context exactly as a `class Const` keyword body
+      # would be. Every other block form — a constant-PATH write (`A::B = Struct.new do … end`, which has no
+      # constant-keyed registration) or a shape the ScopeIndexer's stricter argument check rejects
+      # (`Const = Struct.new(*names) do … end`) — was registered under the call site's anonymous name and is
+      # entered under that.
+      def meta_new_constant_body_context(node)
+        call_node = node.value
+        return nil unless call_node.is_a?(Prism::CallNode) && call_node.block.is_a?(Prism::BlockNode)
+
+        if node.is_a?(Prism::ConstantWriteNode) && ScopeIndexer.meta_new_block_body(node)
+          return @class_context + [ClassFrame.new(name: node.name.to_s, singleton: false)]
+        end
+
+        anonymous = AnonymousMetaClass.name_for(call_node, scope.source_path)
+        anonymous && [ClassFrame.new(name: anonymous, singleton: false)]
+      end
+
       # Slice 7 phase 3 — compound writes (||=, &&=, +=/-=/...) for every variable kind. Each handler:
       #   1. Reads the current type from the appropriate scope
       #      binding map (or `Dynamic[Top]` when unbound).
@@ -432,12 +492,72 @@ module Rigor
 
         key_node = first_index_argument(node)
         address = key_node && IndexedNarrowing.stable_address(node.receiver, key_node)
+        # Issue #544 — a receiver with an untracked (Dynamic / Top) constituent can hold a caller-supplied
+        # slot value the `||=` keeps, so the recorded default would invent a fact; decline the record.
+        address = nil if address && !IndexedNarrowing.fully_tracked_receiver_type?(scope.type_of(node.receiver))
         post = post_rhs
+        # Widen BEFORE recording the narrowing: rebinding the receiver drops the per-slot narrowings keyed on it, so
+        # the reverse order would trade this feature away for the widening. The two are complementary — the shape
+        # forgets that the collection is still empty, the narrowing remembers that THIS slot is now non-nil.
+        post = IndexWriteWidening.widen(node: node, current_scope: post,
+                                        arg_types: index_write_arg_types(node, result_type))
         post = post.with_indexed_narrowing(*address, result_type) if address
 
         [result_type, post]
       end
 
+      # `h[k] &&= v` / `h[k] += v`. Neither had a handler, so both fell to `evaluate`'s default — typed as a pure
+      # expression, scope untouched — and the receiver never widened. They store through `[]=` exactly as
+      # `eval_index_or_write` does, so they take the same widening; the value itself is still typed by the expression
+      # typer (`type_of_assignment_write`), which is what the default did.
+      def eval_index_write(node)
+        stored = scope.type_of(node, tracer: tracer)
+        [stored,
+         IndexWriteWidening.widen(node: node, current_scope: scope,
+                                  arg_types: index_write_arg_types(node, stored))]
+      end
+
+      # `[key_type, stored_value_type]` for an index-write node, shaped exactly like a `[]=` call's
+      # argument list so the widening seam can join it the same way (issue #560). The stored value is
+      # the node's OWN expression type — for `t[0] += 5` that is the compound machinery's already-computed
+      # `t[0] + 5`, which is the whole point: it is the value the mutation put in the slot, and the one
+      # the retained element evidence provably no longer covers. Returns `[]` when the key is unresolvable,
+      # which reproduces the pre-join widening.
+      # There is deliberately NO `rescue` here. `Scope#type_of` is a total query over well-formed Prism input,
+      # so a raise is an engine bug, and swallowing it would silently downgrade a live seam to "no evidence" —
+      # the join would quietly stop happening with nothing to show for it. Let it reach the runner's
+      # internal-error path, where it is visible.
+      def index_write_arg_types(node, stored_type)
+        key_node = first_index_argument(node)
+        return MutationWidening::NO_ARG_TYPES if key_node.nil? || stored_type.nil?
+        return MutationWidening::NO_ARG_TYPES unless MutationWidening.joinable_receiver?(node.receiver, scope)
+
+        [scope.type_of(key_node, tracer: tracer), stored_type]
+      end
+
+      # Argument types for a straight-line content mutator (`arr << x`, `h[k] = v`).
+      #
+      # **The two scopes are different on purpose.** `current_scope` is the post-call scope the widening will
+      # actually rewrite, so the receiver gate has to ask IT whether the binding is still a literal-shape
+      # carrier — asking the entry scope could green-light a join the widening then declines, or miss one it
+      # would make. The arguments, though, are evaluated BEFORE the call in Ruby's order, so their types come
+      # from the entry `scope`; that also matches how the block path types its own mutator arguments against
+      # the block-ENTRY scope. Between the two points the only edits to the scope are the block / escape /
+      # plugin-assertion helpers above, none of which can rebind a mutator call's argument expressions.
+      #
+      # Both gates are about cost, not correctness — the join declines on its own in either case.
+      # `Scope#type_of` builds a fresh `ExpressionTyper` per call and memoizes nothing, so typing arguments a
+      # join will not consume is pure overhead, and `<<` on a String buffer is one of the commonest calls
+      # there is. The content-adder table skips a non-adding mutator (`pop`, `sort!`); `joinable_receiver?`
+      # skips a receiver whose current binding is not a literal-shape carrier.
+      def mutator_arg_types(call_node, current_scope)
+        return MutationWidening::NO_ARG_TYPES unless ContentJoin::CONTENT_ADDERS.include?(call_node.name)
+        return MutationWidening::NO_ARG_TYPES unless MutationWidening.joinable_receiver?(call_node.receiver,
+                                                                                         current_scope)
+
+        content_arg_types(call_node, scope)
+      end
+
       def first_index_argument(node)
         args = node.arguments
         return nil if args.nil?
@@ -562,21 +682,33 @@ module Rigor
       # non-falsey carriers like `Nominal[Integer]` (Integer is always truthy in Ruby — including 0) also collapse the
       # dead else.
       def live_branch_for_if(node, pred_type, post_pred)
-        verdict = optimistic_carrier?(node.predicate, post_pred) ? nil : Narrowing.predicate_certainty(pred_type)
-        case verdict
+        case branch_certainty(node.predicate, pred_type, post_pred)
         when :truthy then eval_branch_or_nil(node.statements, post_pred)
         when :falsey then eval_branch_or_nil(node.subsequent, post_pred)
         end
       end
 
       def live_branch_for_unless(node, pred_type, post_pred)
-        verdict = optimistic_carrier?(node.predicate, post_pred) ? nil : Narrowing.predicate_certainty(pred_type)
-        case verdict
+        case branch_certainty(node.predicate, pred_type, post_pred)
         when :truthy then eval_branch_or_nil(node.else_clause, post_pred)
         when :falsey then eval_branch_or_nil(node.statements, post_pred)
         end
       end
 
+      # ADR-47 WD5 — a decidable **version guard** answers first (#627). `RUBY_VERSION >= "3.1"` and the
+      # `Gem::Version.new(…) <cmp> Gem::Version.new(…)` spellings fold from literals the analyzer can read, so the arm
+      # that cannot run on the Ruby being checked with is elided exactly as `if false`'s is: it is never evaluated, so
+      # it contributes no diagnostics and its writes do not join into the post-`if` scope. The guard expression's own
+      # type stays `bool`, which is what keeps `flow.always-truthy-condition` off it — a version guard is intentional,
+      # not a redundant condition. See {VersionGuard} for the folded shapes and the reference-Ruby premise.
+      def branch_certainty(predicate, pred_type, post_pred)
+        guard = VersionGuard.verdict(predicate)
+        return guard if guard
+        return nil if optimistic_carrier?(predicate, post_pred)
+
+        Narrowing.predicate_certainty(pred_type)
+      end
+
       # ADR-101 — the branch elision MUST NOT conclude truthiness from a carrier whose nil-freeness rests on
       # the `%a{implicitly-returns-nil}` that `RbsDispatch` reads past. Such a value is optimistic, not proof
       # (see {Inference::OptimisticOrigin} and docs/internal-spec/inference-engine.md), so eliding an arm on
@@ -912,7 +1044,7 @@ module Rigor
         # writeback (a loop may content-mutate a collection without rebinding any local — `acc << x`), so apply it to
         # the single-pass join before returning.
         if names.empty?
-          fast = loop_content_writeback(node.statements, base_scope)
+          fast = loop_content_writeback(node.statements, base_scope, pre_body: post_pred)
           return [Type::Combinator.constant_of(nil), narrow_loop_exit_edge(node, fast)]
         end
 
@@ -941,9 +1073,9 @@ module Rigor
         post_loop = result.reduce(base_scope) { |acc, (name, type)| acc.with_local(name, type) }
         # ADR-56 slice C — loop-body receiver-content element-type join. A loop that content-mutates a collection (`acc
         # << n`) keeps only the seed's element types after the single-pass widen; join the appended/stored types into
-        # the continuation collection (pre-state read from `post_loop` so a local both rebound and content-mutated
-        # composes).
-        loop_content_writeback(node.statements, post_loop)
+        # the continuation collection. Pre-state comes from `post_pred` for a name the loop only content-mutates and
+        # from `post_loop` for one it also rebinds, so composition still works — see {#loop_content_writeback}.
+        loop_content_writeback(node.statements, post_loop, pre_body: post_pred, rebound: names)
       end
 
       # Item 4 — loop-exit predicate narrowing. A `while pred` / `until pred` loop exits PRECISELY on the predicate's
@@ -1053,9 +1185,25 @@ module Rigor
       # Joins loop-body content mutations into the continuation collection bindings. The mutator arguments are typed
       # against `post_loop`, whose locals already carry the loop-body fixpoint widening (so an appended `n` that the
       # loop decrements types `Integer`, not its entry `Constant[3]` — otherwise only the first iteration's value would
-      # be captured, an unsound under-approximation). Pre-state is read from `post_loop` too. A loop body shares the
-      # surrounding scope, so the receiver is any `LocalVariableReadNode` (no depth filter).
-      def loop_content_writeback(statements, post_loop)
+      # be captured, an unsound under-approximation). A loop body shares the surrounding scope, so the receiver is any
+      # `LocalVariableReadNode` (no depth filter).
+      #
+      # **Pre-state comes from `pre_body` — the scope as of the loop predicate — for every name the loop does not
+      # REBIND.** `post_loop` derives from a body evaluation, so the straight-line join inside the body has already
+      # written its own result into that binding, floor and all (issue #560: a straight-line seam sees one store, so it
+      # never closes the parameter it feeds). Re-deriving on top of that is derivation on derived output: this seam
+      # scans the WHOLE body and joins every store in it, so it wants the contents as they stood before the body ran
+      # and re-adds the stores itself. Left on `post_loop`, ADR-56's own `acc = []; while …; acc.push(m); end` read
+      # `Array[Dynamic[top] | Integer]` where it must read `Array[Integer]`.
+      #
+      # Scrubbing the floor back out of `post_loop` instead is NOT an option: once inside a union a `Dynamic` is
+      # indistinguishable from a DECLARED one, and stripping it closes a declared `Array[Integer | untyped]` parameter
+      # and draws a false `undefined method` on correct code. Telling the two apart needs provenance the carriers do
+      # not have (issue #580); taking the pre-body binding sidesteps the question entirely.
+      #
+      # A name the loop rebinds keeps reading `post_loop`, which is what lets a local both rebound (slice B) and
+      # content-mutated compose — the documented behaviour, and there the fixpoint's answer IS the right base.
+      def loop_content_writeback(statements, post_loop, pre_body: nil, rebound: nil)
         return post_loop if statements.nil?
 
         mutations = Hash.new { |h, k| h[k] = [] }
@@ -1066,11 +1214,20 @@ module Rigor
         return post_loop if mutations.empty?
 
         mutations.reduce(post_loop) do |acc, (name, calls)|
-          joined = join_content_for_local(name, calls, acc, post_loop)
+          joined = join_content_for_local(name, calls, content_seed_scope(name, acc, pre_body, rebound), post_loop)
           joined.nil? ? acc : acc.with_local(name, joined)
         end
       end
 
+      # The scope a loop content join reads its PRE-STATE from: the pre-body scope for a name the loop only
+      # content-mutates, and the accumulating post-loop scope for one the loop also rebinds. {#loop_content_writeback}
+      # carries the why.
+      def content_seed_scope(name, accumulated, pre_body, rebound)
+        return accumulated if pre_body.nil? || rebound&.include?(name)
+
+        pre_body
+      end
+
       # Re-evaluates the loop body once from the converged fixpoint bindings, solely for the `on_enter` side effect of
       # re-recording the body's per-node entry scopes. Gated behind the display-path-only `converged_loop_recording`
       # flag so the check path neither pays the extra body evaluation nor risks any diagnostic drift.
@@ -1104,7 +1261,7 @@ module Rigor
         pre_existing = []
         body_first = []
         Source::NodeWalker.each(statements) do |descendant|
-          next unless LOCAL_WRITE_NODES.any? { |klass| descendant.is_a?(klass) }
+          next unless CapturedLocals::LOCAL_WRITE_NODES.any? { |klass| descendant.is_a?(klass) }
 
           name = descendant.name
           if base_scope.locals.key?(name)
@@ -1305,10 +1462,19 @@ module Rigor
       # lexical owner. The outer scope is unchanged on exit because Ruby's class definition does not bind any local in
       # the enclosing scope. The class body's value is the value of its last statement (`Constant[nil]` for an empty
       # body); we discard the body's post-scope.
+      #
+      # Issue #708 — a ROOTED header (`class ::Rooted::Bar`) re-anchors at the top level, so the frame stack
+      # RESETS to that class alone rather than gaining a frame under the enclosure. `current_class_path` joins
+      # the stack, so keeping the enclosing frames named the class `Outer::Rooted::Bar` and every `def` in it
+      # registered under a name no caller writes. The nesting CHAIN is not reset the same way — Ruby leaves the
+      # enclosing entries beneath the un-prefixed one — which is why {Source::ConstantPath.pushed_nesting} owns
+      # that half rather than this one deriving it from the frames.
       def eval_class_or_module(node)
-        name = Source::ConstantPath.qualified_name(node.constant_path)
-        new_context = @class_context + [ClassFrame.new(name: name, singleton: false)]
-        body_type, _body_scope = eval_class_body(node, new_context)
+        path = node.constant_path
+        frame = ClassFrame.new(name: Source::ConstantPath.qualified_name(path), singleton: false)
+        new_context = Source::ConstantPath.rooted?(path) ? [frame] : @class_context + [frame]
+        body_type, _body_scope = eval_class_body(node, new_context,
+                                                 Source::ConstantPath.pushed_nesting(@lexical_nesting, path))
         [body_type, scope]
       end
 
@@ -1316,6 +1482,13 @@ module Rigor
       # class — the innermost frame flips to `singleton: true` so a nested `def foo` resolves through `singleton_method`
       # rather than `instance_method`. For non-`self` expressions we cannot statically resolve the receiver, so we keep
       # the existing context and accept that nested defs degrade to the `Dynamic[Top]` default.
+      # Issue #652 — the body INHERITS this evaluator's chain. Ruby pushes the singleton class onto
+      # `Module.nesting` and leaves the enclosing entries beneath it, so `class << Other` written inside
+      # `module Admin` reads `Admin::Y`: the enclosing rung is live, and only the singleton rung itself
+      # (`#<Class:Other>`) is one Rigor does not model, on either path
+      # ([#662](https://github.com/rigortype/rigor/issues/662)). Discarding the chain here because
+      # {#singleton_context_for} resets the FRAME STACK for the cross-class form would answer `Other::Y`
+      # off the name-peel instead — a rung Ruby's lookup does not have at all.
       def eval_singleton_class(node)
         new_context = singleton_context_for(node)
         body_type, _body_scope = eval_class_body(node, new_context)
@@ -1384,7 +1557,8 @@ module Rigor
         # Flow-folding G1 / G2 — widen a local- or instance-variable binding when the call is an in-place mutator on it
         # (e.g. `arms << x`, `@tags << hashtag`). Stops a literal-shape carrier (`Tuple` / `HashShape`) from outliving
         # its justification when the value is mutated. Always-safe (loses precision, never invents facts).
-        post_scope = MutationWidening.widen_after_call(call_node: node, current_scope: post_scope)
+        post_scope = MutationWidening.widen_after_call(call_node: node, current_scope: post_scope,
+                                                       arg_types: mutator_arg_types(node, post_scope))
         # ADR-48 slice 4 — Struct member-setter re-typing. After `s.x = v` on a fold-safe StructInstance local, rebind
         # `s` to a StructInstance with member `:x` replaced by the assigned type, so a later `s.x` folds to `v` and a
         # sibling `s.y` stays precise. `call_type` is the setter's own result (the assigned value type). Sound only for
@@ -1402,11 +1576,16 @@ module Rigor
         post_scope = widen_callee_escaped_argument_captures(node, post_scope)
         # Same always-safe rationale as `widen_after_call` above — propagates outer-scope local / ivar widening from
         # block body mutations (`items.each { |x| arr << x }`).
+        #
+        # The slice-C join below reads its SEED from here, before the widening runs: `widen_after_block` spells an
+        # empty `[]` as `Array[untyped]`, and read back after the fact that `untyped` is indistinguishable from a
+        # declared one (issue #586 — see {#content_writeback_block_captures}).
+        pre_widen_scope = post_scope
         post_scope = MutationWidening.widen_after_block(call_node: node, outer_scope: post_scope)
         # ADR-56 slice C — receiver-content element-type join. Joins appended / stored element / key / value types into
         # the continuation collection so `out = [0]; arr.each { |x| out << x }` types `Array[0 | Integer]`, not
         # `Array[0]`. Same always-safe rationale (only widens).
-        post_scope = content_writeback_block_captures(node, post_scope)
+        post_scope = content_writeback_block_captures(node, post_scope, seed_scope: pre_widen_scope)
         # Indexed-collection narrowing — drop any `receiver[key] ||= default` narrowing the analyzer recorded earlier
         # when an intervening `[]=` writes the same slot or any other mutator runs against the receiver. Always-safe
         # (only forgets; never invents).
@@ -1428,6 +1607,10 @@ module Rigor
         # whose body we cannot prove match-free). A call provably match-free on a known receiver — `$3.to_i`, `year <
         # 50` — does NOT clobber, so the multi-statement `m = /…/ =~ s; …; use($2)` stdlib idiom keeps its precision
         # while a genuinely interposed match still invalidates.
+        # The chain above is Scope-total by construction (every helper returns its input scope or a
+        # combinator result); the `||=` is a runtime no-op that pins the INFERRED type back to Scope for
+        # the negative rules when a helper's return widens to `Scope?` under call-site binding (#524).
+        post_scope ||= scope
         post_scope = post_scope.forget_match_globals if match_capable_call?(node)
         [call_type, post_scope]
       end
@@ -1466,12 +1649,14 @@ module Rigor
         seed = current_scope.class_ivars_for(class_name)
         return current_scope if seed.empty?
 
-        seed.reduce(current_scope) do |acc, (ivar_name, seed_type)|
+        widened = current_scope
+        seed.each do |ivar_name, seed_type|
           local_type = current_scope.ivar(ivar_name)
-          next acc if local_type.nil? || local_type == seed_type
+          next if local_type.nil? || local_type == seed_type
 
-          acc.with_ivar(ivar_name, Type::Combinator.union(local_type, seed_type))
+          widened = widened.with_ivar(ivar_name, Type::Combinator.union(local_type, seed_type))
         end
+        widened
       end
 
       def intervening_call_candidate?(call_node)
@@ -1835,8 +2020,24 @@ module Rigor
         anonymous = AnonymousMetaClass.name_for(node, scope.source_path)
         return sub_eval(block, block_entry) if anonymous.nil?
 
-        sub_eval(block, block_entry.with_self_type(Type::Combinator.singleton_of(anonymous)),
-                 class_context: [ClassFrame.new(name: anonymous, singleton: false)])
+        enter_meta_class_body(block, block_entry, [ClassFrame.new(name: anonymous, singleton: false)])
+      end
+
+      # Enters a meta-new `block` as the body of the class `class_context` names: `self_type` is that class's
+      # singleton, so a `def` inside binds an instance method on it through the ordinary
+      # {#self_type_for_method_body} route, while `block_entry` keeps the outer locals visible. Shared by the two
+      # positions such a block is reached from — a statement-level call ({#evaluate_block_if_present}) and a
+      # constant-write rvalue ({#eval_constant_write}) — so the two cannot drift on what a class body's entry is.
+      #
+      # Issue #652 — the body keeps this evaluator's `Module.nesting`. A BLOCK never pushes a cref, however
+      # much `class_eval` semantics make it behave like a class body in every other respect, so
+      # `K = Class.new do … end` written inside `module Outer` reads `Outer::LABEL` at runtime and MUST NOT
+      # record a `Outer::K` entry: that is a rung Ruby's constant lookup does not have. The `class_context`
+      # frame is still pushed — it is what a nested `def` registers its method under — which is exactly the
+      # divergence that makes the chain a separate record rather than a view of the frame stack.
+      def enter_meta_class_body(block, block_entry, class_context)
+        entry = block_entry.with_self_type(self_type_for_class_body(class_context))
+        sub_eval(block, stamp_nesting(entry, @lexical_nesting), class_context: class_context)
       end
 
       # Slice 6 phase C sub-phase 3b/3c. When the call carries a block whose receiving method is NOT proven
@@ -2165,42 +2366,12 @@ module Rigor
       # synthesise the union of the block's write types (which the current pass does not yet expose), we discard the
       # narrowed binding altogether. A future sub-phase MAY refine this to the union of the block's actual writes.
       def drop_captured_narrowing(block_node, base_scope)
-        names = captured_local_writes(block_node, base_scope)
+        names = CapturedLocals.writes(block_node, base_scope)
         return base_scope if names.empty?
 
         names.reduce(base_scope) { |acc, name| acc.with_local(name, Type::Combinator.untyped) }
       end
 
-      # Names of outer locals the block body can REBIND, across every local-write form: plain `=`
-      # (`LocalVariableWriteNode`), the operator / `||=` / `&&=` compound forms, and a multi-assign target (`x, y = ...`
-      # → `LocalVariableTargetNode` under `MultiWriteNode`). Block-introduced names (parameters, numbered params,
-      # `;`-locals) and names not bound in the outer scope are excluded — a write to either is not a captured rebind of
-      # an outer variable.
-      LOCAL_WRITE_NODES = [
-        Prism::LocalVariableWriteNode,
-        Prism::LocalVariableOperatorWriteNode,
-        Prism::LocalVariableOrWriteNode,
-        Prism::LocalVariableAndWriteNode,
-        Prism::LocalVariableTargetNode
-      ].freeze
-      private_constant :LOCAL_WRITE_NODES
-
-      def captured_local_writes(block_node, base_scope)
-        body = block_node.body
-        return [] if body.nil?
-
-        introduced = block_introduced_locals(block_node)
-        outer_writes = []
-        Source::NodeWalker.each(body) do |descendant|
-          next unless LOCAL_WRITE_NODES.any? { |klass| descendant.is_a?(klass) }
-          next if introduced.include?(descendant.name)
-          next unless base_scope.locals.key?(descendant.name)
-
-          outer_writes << descendant.name
-        end
-        outer_writes.uniq
-      end
-
       # ADR-56 slice A. For a `:non_escaping` block, fold the continuation binding of every outer local the body can
       # rebind back into `post_scope`. The binding is a capped fixpoint (cap 3) over the block body re-evaluated under
       # the running per-name assumption, joined with the pre-call binding (kept as a constituent so the 0-iteration path
@@ -2208,13 +2379,13 @@ module Rigor
       # `Dynamic[top]` on non-convergence (matching `drop_captured_narrowing`).
       #
       # Fast path: a block writing no outer local leaves `post_scope` byte-identical (the overwhelming majority of
-      # blocks), so this costs one extra `captured_local_writes` walk and nothing else.
+      # blocks), so this costs one extra `CapturedLocals.writes` walk and nothing else.
       def write_back_block_captures(call_node, post_scope)
         block = call_node.block
         return post_scope unless block.is_a?(Prism::BlockNode)
         return post_scope unless classify_closure_escape(call_node) == :non_escaping
 
-        names = captured_local_writes(block, scope)
+        names = CapturedLocals.writes(block, scope)
         return post_scope if names.empty?
 
         seed = names.to_h { |name| [name, scope.local(name)] }
@@ -2234,11 +2405,20 @@ module Rigor
       # collection's parameter, so `out = [0]; arr.each { |x| out << x }` types `out` as `Array[0 | Integer]` (sound)
       # rather than `Array[0]` (the B1 under-approximation: the runtime array is `[0, 1, 2, 3]`).
       #
-      # Pre-state is read from `post_scope` so a local that is BOTH rebound and content-mutated composes: the rebind
-      # fixpoint result feeds the content join. The block body is typed once for argument evidence; the floor is
-      # `Array[Dynamic[top]]` / `Hash[untyped, untyped]` (the sound empty-seed behaviour). Always sound — only ever
-      # widens.
-      def content_writeback_block_captures(call_node, post_scope)
+      # **Pre-state is read from `seed_scope` — the scope as it stood BEFORE `widen_after_block` ran.** The widening
+      # spells an empty `[]` as `Array[untyped]`, and read back after the fact that `untyped` cannot be told from a
+      # DECLARED one: the join used to drop every seed `Dynamic` once the body contributed concrete evidence, which
+      # made `out = []; xs.each { out << x }` read `Array[Integer]` — and closed a parameter declared `Array[untyped]`
+      # to `Array[Integer]` on the same rule, so `a.first.upcase` drew `undefined method` on code the declaration
+      # licenses (issue #586). Read before the widening, an empty literal contributes no element and a declared
+      # gradual arm is just another seed arm the join keeps. The pre-widen scope still carries the slice-A rebind
+      # write-back — so a local that is BOTH rebound and content-mutated composes as before — and every other
+      # post-call effect applied ahead of the widening; the pre-CALL `scope` would carry neither. The loop seam makes
+      # the same choice with `pre_body`; see {#loop_content_writeback}.
+      #
+      # The block body is typed once for argument evidence; the floor is `Array[Dynamic[top]]` /
+      # `Hash[untyped, untyped]` (the sound empty-seed behaviour). Always sound — only ever widens.
+      def content_writeback_block_captures(call_node, post_scope, seed_scope:)
         block = call_node.block
         return post_scope unless block.is_a?(Prism::BlockNode)
         return post_scope unless classify_closure_escape(call_node) == :non_escaping
@@ -2251,7 +2431,7 @@ module Rigor
 
         entry = build_block_entry_scope(call_node, block)
         mutations.reduce(post_scope) do |acc, (name, calls)|
-          joined = join_content_for_local(name, calls, acc, entry)
+          joined = join_content_for_local(name, calls, seed_scope, entry)
           joined.nil? ? acc : acc.with_local(name, joined)
         end
       end
@@ -2308,7 +2488,7 @@ module Rigor
         calls = []
         Source::NodeWalker.each(body) do |descendant|
           next unless descendant.is_a?(Prism::CallNode)
-          next unless MutationWidening::CONTENT_ADDERS.include?(descendant.name)
+          next unless ContentJoin::CONTENT_ADDERS.include?(descendant.name)
 
           receiver = descendant.receiver
           next unless receiver.is_a?(Prism::LocalVariableReadNode)
@@ -2320,7 +2500,11 @@ module Rigor
       end
 
       # Joins content evidence for a memo / param given its pre-state and a list of mutator calls, dispatching Array vs
-      # Hash by the mutator set.
+      # Hash by the PRE-STATE's own evidence. The mutator set never picks the arm on its own: `[]=` is legal on Array,
+      # Hash, and countless index-writable classes, so an index-write against a receiver the engine cannot shape must
+      # not synthesize a hash carrier — mail's `compose_codepoints` mutated its untyped Array param through
+      # integer/range index writes and returned `Hash[Integer | Range, …]` to its caller (issue #553). Dynamic in,
+      # Dynamic out: a shapeless pre-state falls through to `join_array_param`, which declines it.
       def join_content_for_param(calls, pre_state, block_entry)
         return nil if pre_state.nil?
 
@@ -2328,7 +2512,7 @@ module Rigor
           # String carries no element parameter; mutating `<<`/`concat` makes the constant value unsound (`s = "a"; s <<
           # x` → runtime `"a…"`), so widen to the nominal base. Sound — only widens.
           Type::Combinator.nominal_of("String")
-        elsif hashish?(pre_state) || (hash_mutations?(calls) && !arrayish?(pre_state))
+        elsif hashish?(pre_state)
           join_hash_param(calls, pre_state, block_entry)
         else
           join_array_param(calls, pre_state, block_entry)
@@ -2339,7 +2523,7 @@ module Rigor
         pairs = calls.flat_map { |c| hash_pair_types(c, block_entry) }
         return nil if pairs.empty? && !hashish?(pre_state)
 
-        MutationWidening.join_hash_content(pre_state, pairs)
+        ContentJoin.join_hash_content(pre_state, pairs)
       end
 
       def join_array_param(calls, pre_state, block_entry)
@@ -2350,9 +2534,9 @@ module Rigor
           # array-arity forget already widened the binding; contribute nothing.
           next [] if index_write?(c)
 
-          MutationWidening.array_added_elements(c.name, content_arg_types(c, block_entry))
+          ContentJoin.array_added_elements(c.name, content_arg_types(c, block_entry))
         end
-        MutationWidening.join_array_content(pre_state, added)
+        ContentJoin.join_array_content(pre_state, added)
       end
 
       # Walks the block body for content-mutator calls (`<<`, `push`, `[]=`, …) whose receiver is a captured outer local
@@ -2381,7 +2565,7 @@ module Rigor
       # `[receiver_name, node]` when `node` is a content mutation whose receiver is a local variable satisfying `accept`
       # (depth predicate), else `[nil, nil]`. Covers `[]=`-style CallNode mutators and the index-write node forms.
       def content_mutation_target(node)
-        is_call_mutator = node.is_a?(Prism::CallNode) && MutationWidening::CONTENT_ADDERS.include?(node.name)
+        is_call_mutator = node.is_a?(Prism::CallNode) && ContentJoin::CONTENT_ADDERS.include?(node.name)
         return [nil, nil] unless is_call_mutator || index_write?(node)
 
         receiver = node.receiver
@@ -2398,21 +2582,19 @@ module Rigor
         join_content_for_param(calls, post_scope.local(name), block_entry)
       end
 
-      def hash_mutations?(calls)
-        calls.any? do |c|
-          index_write?(c) || (c.is_a?(Prism::CallNode) && MutationWidening::HASH_CONTENT_ADDERS.include?(c.name))
-        end
-      end
-
       def index_write?(node)
         INDEX_WRITE_NODES.any? { |k| node.is_a?(k) }
       end
 
+      # A `Difference` (`non-empty-array[T]`) counts as its base. The seams read their seed from before the mutation
+      # widening ran, so they meet the refinement carrier where they used to meet the `Array[T]` it widens to;
+      # declining it would leave the continuation on that widened base with every appended arm missing.
       def arrayish?(type)
         case type
         when Type::Tuple then true
         when Type::Nominal then type.class_name == "Array"
         when Type::Union then type.members.any? { |m| arrayish?(m) }
+        when Type::Difference then arrayish?(type.base)
         else false
         end
       end
@@ -2422,6 +2604,7 @@ module Rigor
         when Type::HashShape then true
         when Type::Nominal then type.class_name == "Hash"
         when Type::Union then type.members.any? { |m| hashish?(m) }
+        when Type::Difference then hashish?(type.base)
         else false
         end
       end
@@ -2482,16 +2665,6 @@ module Rigor
         names.to_h { |name| [name, exit_scope.local(name)] }
       end
 
-      # Names introduced by the block itself (parameters, numbered parameters via `BlockParameterBinder`, plus explicit
-      # `;`-prefixed block-locals on `BlockParametersNode`). Writes to these names are local to the block and MUST NOT
-      # be treated as captured rebinds of an outer local.
-      def block_introduced_locals(block_node)
-        introduced = Set.new(BlockParameterBinder.new.bind(block_node).keys)
-        params_root = block_node.parameters
-        params_root.locals.each { |loc| introduced << loc.name } if params_root.is_a?(Prism::BlockParametersNode)
-        introduced
-      end
-
       # `Prism::BlockNode` is reached through {#eval_call}; the handler runs the body under `scope`, which the caller
       # has already augmented with the block's parameter bindings. Effects do not leak past the block (the outer
       # eval_call returns the caller's scope unchanged), but the body's local writes are threaded through subsequent
@@ -2554,7 +2727,7 @@ module Rigor
 
       # ----- def/class helpers -----
 
-      def eval_class_body(node, new_context)
+      def eval_class_body(node, new_context, new_nesting = @lexical_nesting)
         return [Type::Combinator.constant_of(nil), scope] if node.body.nil?
 
         # Class/module bodies run in a fresh scope: the outer scope's locals are NOT visible inside `class Foo; ...
@@ -2564,7 +2737,8 @@ module Rigor
         fresh = build_fresh_body_scope
         body_self = self_type_for_class_body(new_context)
         fresh = fresh.with_self_type(body_self) if body_self
-        sub_eval(node.body, fresh, class_context: new_context)
+        fresh = stamp_nesting(fresh, new_nesting)
+        sub_eval(node.body, fresh, class_context: new_context, lexical_nesting: new_nesting)
       end
 
       def build_method_entry_scope(def_node) # rubocop:disable Metrics/AbcSize
@@ -2591,6 +2765,9 @@ module Rigor
         fresh = build_fresh_body_scope
         body_self = self_type_for_method_body(singleton: singleton)
         fresh = fresh.with_self_type(body_self) if body_self
+        # A `def` opens no new `Module.nesting` entry — the body resolves constants against the chain of the
+        # declaration that encloses it, which is what the evaluator is already carrying (#652).
+        fresh = stamp_nesting(fresh, @lexical_nesting)
         fresh = seed_instance_ivars(fresh, singleton: singleton)
         fresh = seed_class_cvars(fresh)
         fresh = seed_program_globals(fresh)
@@ -2806,6 +2983,14 @@ module Rigor
         end
       end
 
+      # Stamps a recorded chain onto a body-entry scope. An empty chain (a top-level body) and an unknown one
+      # are both left unstamped, so `Reflection.lexical_nesting_chain` keeps its peel fallback for them.
+      def stamp_nesting(body_scope, chain)
+        return body_scope if chain.nil? || chain.empty?
+
+        body_scope.with_lexical_nesting(chain)
+      end
+
       # The qualified name of the immediately-enclosing class (joining every nested `ClassFrame` with `::`). Returns
       # `nil` for a top-level def with no enclosing class, which routes the parameter binder past RBS lookup.
       def current_class_path
@@ -2859,12 +3044,13 @@ module Rigor
         end
       end
 
-      def sub_eval(node, with_scope, class_context: @class_context)
+      def sub_eval(node, with_scope, class_context: @class_context, lexical_nesting: @lexical_nesting)
         StatementEvaluator.new(
           scope: with_scope,
           tracer: tracer,
           on_enter: @on_enter,
           class_context: class_context,
+          lexical_nesting: lexical_nesting,
           converged_loop_recording: @converged_loop_recording
         ).evaluate(node)
       end
@@ -3119,6 +3305,5 @@ module Rigor
         merged.to_a
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end