rigortype 0.1.11 → 0.1.12

data/lib/rigor/inference/expression_typer.rb

@@ -6,6 +6,7 @@ require_relative "../type"
 require_relative "../ast"
 require_relative "block_parameter_binder"
 require_relative "fallback"
+require_relative "indexed_narrowing"
 require_relative "macro_block_self_type"
 require_relative "method_dispatcher"
 require_relative "narrowing"
@@ -1133,6 +1134,69 @@ module Rigor
         type_of(body.last)
       end
 
+      # Indexed-collection narrowing — `receiver[key]` after a
+      # prior `receiver[key] ||= default` reads the post-`||=`
+      # type when the receiver and key are stable enough to
+      # address. Sits ahead of `MethodDispatcher.dispatch` so
+      # the standard `Hash#[]` / `Array#[]` answer (which would
+      # fold to `Constant[nil]` for an empty `HashShape{}` or
+      # `Tuple[]`) does not override the narrowing. See
+      # {Inference::IndexedNarrowing}.
+      def indexed_narrowing_for(node)
+        IndexedNarrowing.lookup_for_call(node, scope) || method_chain_narrowing_for(node)
+      end
+
+      # Stable single-hop chain narrowing — `receiver.method`
+      # after an `is_a?` / `kind_of?` / `instance_of?` predicate
+      # established the narrowing on the dominated edge. The
+      # call MUST be no-arg + no-block + rooted at a local-var /
+      # ivar read; everything else falls through to the
+      # standard dispatcher. ROADMAP § Future cycles —
+      # "Method-call receiver narrowing across stable
+      # receivers" — Law-of-Demeter-justified single-hop scope.
+      def method_chain_narrowing_for(node)
+        return nil unless node.is_a?(Prism::CallNode)
+        return nil unless node.block.nil?
+        return nil unless node.arguments.nil? || node.arguments.arguments.empty?
+
+        case node.receiver
+        when Prism::LocalVariableReadNode
+          scope.method_chain_narrowing(:local, node.receiver.name, node.name)
+        when Prism::InstanceVariableReadNode
+          scope.method_chain_narrowing(:ivar, node.receiver.name, node.name)
+        end
+      end
+
+      # v0.0.3 A — implicit-self calls prefer a same-named
+      # top-level `def` over RBS dispatch. Without this,
+      # a helper like `def select(...)` defined inside an
+      # `RSpec.describe ... do ... end` block mis-routes
+      # through `Enumerable#select` / `Object#select` and
+      # the caller observes `Array[Elem]` instead of the
+      # helper's actual return type. The check fires only
+      # for `node.receiver.nil?` (true implicit self), so
+      # explicit-receiver dispatch is unaffected.
+      def try_local_def_dispatch(node, receiver, arg_types)
+        local_def = node.receiver.nil? ? scope.top_level_def_for(node.name) : nil
+        return nil unless local_def
+
+        local_inference = infer_top_level_user_method(local_def, receiver, arg_types)
+        return local_inference if local_inference && adoptable_self_call_result?(local_inference)
+
+        # The local def matches by name but the inference was
+        # disqualified — either the parameter shape is too complex
+        # for the first-iteration binder (kwargs / optionals /
+        # rest), or ADR-24 slice 1's conservative gate declined
+        # the resolved return type inside a class body (see
+        # `adoptable_self_call_result?`). `Dynamic[Top]` is the
+        # safest answer: RBS dispatch would be wrong (the method
+        # is user-defined and shadows whatever ancestor method the
+        # dispatch would find), and `Dynamic[Top]` propagates
+        # correctly through downstream call chains without
+        # surfacing misleading false-positive diagnostics.
+        dynamic_top
+      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
@@ -1140,40 +1204,15 @@ module Rigor
       # 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)
+        narrowed = indexed_narrowing_for(node)
+        return narrowed if narrowed
+
         receiver = call_receiver_type_for(node)
         arg_types = call_arg_types(node)
         block_type = block_return_type_for(node, receiver, arg_types)
 
-        # v0.0.3 A — implicit-self calls prefer a same-named
-        # top-level `def` over RBS dispatch. Without this,
-        # a helper like `def select(...)` defined inside an
-        # `RSpec.describe ... do ... end` block mis-routes
-        # through `Enumerable#select` / `Object#select` and
-        # the caller observes `Array[Elem]` instead of the
-        # helper's actual return type. The check fires only
-        # for `node.receiver.nil?` (true implicit self), so
-        # explicit-receiver dispatch is unaffected.
-        local_def = node.receiver.nil? ? scope.top_level_def_for(node.name) : nil
-        if local_def
-          local_inference = infer_top_level_user_method(local_def, receiver, arg_types)
-          return local_inference if local_inference && adoptable_self_call_result?(local_inference)
-
-          # The local def matches by name but the inference
-          # was disqualified — either the parameter shape is
-          # too complex for the first-iteration binder
-          # (kwargs / optionals / rest), or ADR-24 slice 1's
-          # conservative gate declined the resolved return
-          # type inside a class body (see
-          # `adoptable_self_call_result?`).
-          # Returning `Dynamic[Top]` is the safest answer:
-          # we know RBS dispatch would be wrong (the
-          # method is user-defined and shadows whatever
-          # ancestor method the dispatch would find), and
-          # `Dynamic[Top]` propagates correctly through
-          # downstream call chains without surfacing
-          # misleading false-positive diagnostics.
-          return dynamic_top
-        end
+        local_def_result = try_local_def_dispatch(node, receiver, arg_types)
+        return local_def_result if local_def_result
 
         # v0.0.6 phase 2 — per-element block fold for Tuple
         # receivers. When `[a, b, c].map { |x| f(x) }` and the

data/lib/rigor/inference/indexed_narrowing.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../type"
+require_relative "mutation_widening"
+
+module Rigor
+  module Inference
+    # Closes the "`params[:f] ||= []; params[:f] << x`" precision
+    # gap surfaced by the Redmine 6.1.2 `Query#as_params` survey
+    # (ROADMAP § Future cycles / Type-language / engine —
+    # "Indexed-collection narrowing through `Hash[k] ||= default`").
+    #
+    # After `receiver[key] ||= default` the next read at
+    # `receiver[key]` is known non-nil, but Rigor types each
+    # `Hash#[]` independently and the subsequent `<<` / `[]=` /
+    # other mutator dispatches against the un-narrowed result —
+    # which on a `HashShape{}` carrier folds to `Constant[nil]`.
+    #
+    # This module is the address-recogniser + invalidator shared
+    # by {Inference::StatementEvaluator}'s `eval_index_or_write`
+    # handler (which RECORDS the narrowing) and `eval_call`
+    # (which INVALIDATES on intervening writes / mutators) and
+    # by {Inference::ExpressionTyper}'s `call_type_for` (which
+    # CONSUMES the narrowing when typing a follow-up `[]` read).
+    #
+    # **Stable receivers.** A receiver is "stable" iff it is a
+    # `LocalVariableReadNode` or `InstanceVariableReadNode`.
+    # Method-call chains (`foo.bar[:k]`) and other shapes are
+    # rejected because a follow-up read against an identical-
+    # looking AST chain has no guarantee of resolving to the
+    # same runtime value — narrowing it would invent a fact.
+    #
+    # **Stable keys.** A key is "stable" iff it is a literal
+    # `SymbolNode` / `StringNode` / `IntegerNode`. Local-variable
+    # keys (`params[field]`) are excluded for the same
+    # invent-a-fact reason: the local could be rebound between
+    # the `||=` and the read.
+    #
+    # **Invalidation.** Three conditions drop a recorded
+    # narrowing:
+    # - The receiver variable is rebound (handled inside
+    #   `Scope#with_local` / `Scope#with_ivar`).
+    # - An intervening `receiver[key] = value` writes the same
+    #   slot — `:[]=` could rebind the slot to nil; conservative
+    #   drop.
+    # - An intervening mutator from {MutationWidening::HASH_MUTATORS}
+    #   or {MutationWidening::ARRAY_MUTATORS} runs against the
+    #   receiver (e.g. `params.delete(:f)`, `params.clear`).
+    #
+    # All three are implemented in `StatementEvaluator#eval_call`'s
+    # post-dispatch path through {.invalidate_after_call}.
+    module IndexedNarrowing
+      # Literal Prism nodes whose Ruby value the analyzer trusts
+      # as a stable address. Symbol / String are the dominant
+      # Hash key shapes; Integer covers numerically-keyed Hashes
+      # and Array indices.
+      STABLE_KEY_NODES = [Prism::SymbolNode, Prism::StringNode, Prism::IntegerNode].freeze
+
+      module_function
+
+      # Returns `[receiver_kind, receiver_name]` when `node` is a
+      # `LocalVariableReadNode` or `InstanceVariableReadNode`,
+      # otherwise nil.
+      def stable_receiver(node)
+        case node
+        when Prism::LocalVariableReadNode then [:local, node.name]
+        when Prism::InstanceVariableReadNode then [:ivar, node.name]
+        end
+      end
+
+      # Returns the literal Ruby value when `node` is a stable
+      # key shape, otherwise nil. Symbols → `Symbol`,
+      # Strings → `String` (unescaped), Integers → `Integer`.
+      def stable_key(node)
+        case node
+        when Prism::SymbolNode then node.unescaped.to_sym
+        when Prism::StringNode then node.unescaped
+        when Prism::IntegerNode then node.value
+        end
+      end
+
+      # Returns `[receiver_kind, receiver_name, key]` when the
+      # CallNode is a `receiver[key]` read or write whose
+      # receiver and key are both stable, otherwise nil. Used
+      # by both the recorder (for `IndexOrWriteNode`'s
+      # receiver/arguments triplet) and the invalidator (for
+      # `CallNode :[]=` / mutator calls). Treats only the FIRST
+      # argument as the key; `:[]=`'s second argument is the
+      # rvalue and is not part of the address.
+      def stable_address(receiver_node, key_node)
+        receiver = stable_receiver(receiver_node)
+        return nil if receiver.nil?
+
+        key = stable_key(key_node)
+        return nil if key.nil?
+
+        [receiver.first, receiver.last, key]
+      end
+
+      # Looks up a recorded narrowing for `receiver[key]` against
+      # `scope`, returning the narrowed type or nil when no
+      # entry applies. Used by ExpressionTyper's `[]` dispatch
+      # to refine the result of a stable indexed read.
+      def lookup_for_call(node, scope)
+        return nil unless node.is_a?(Prism::CallNode)
+        return nil unless node.name == :[]
+        return nil if node.arguments.nil?
+        return nil unless node.arguments.arguments.size == 1
+
+        address = stable_address(node.receiver, node.arguments.arguments.first)
+        return nil if address.nil?
+
+        scope.indexed_narrowing(*address)
+      end
+
+      # Removes recorded narrowings invalidated by `call_node`.
+      # Two patterns:
+      #
+      # - `receiver[key] = value` (a `:[]=` against a stable
+      #   address): drop the specific `(receiver, key)` entry.
+      # - Any mutator from `HASH_MUTATORS` / `ARRAY_MUTATORS`
+      #   against a stable receiver: drop EVERY entry rooted
+      #   at that receiver, because the mutator could rebind
+      #   any slot.
+      #
+      # Returns the updated scope. Always-safe (only forgets;
+      # never invents).
+      def invalidate_after_call(call_node:, current_scope:)
+        return current_scope unless call_node.is_a?(Prism::CallNode)
+
+        if call_node.name == :[]=
+          invalidate_indexed_write(call_node, current_scope)
+        elsif mutator?(call_node.name)
+          invalidate_mutator(call_node, current_scope)
+        else
+          current_scope
+        end
+      end
+
+      def mutator?(method_name)
+        MutationWidening::HASH_MUTATORS.include?(method_name) ||
+          MutationWidening::ARRAY_MUTATORS.include?(method_name)
+      end
+
+      def invalidate_indexed_write(call_node, current_scope)
+        args = call_node.arguments&.arguments
+        return current_scope if args.nil? || args.empty?
+
+        address = stable_address(call_node.receiver, args.first)
+        return current_scope if address.nil?
+
+        current_scope.without_indexed_narrowing(*address)
+      end
+
+      def invalidate_mutator(call_node, current_scope)
+        receiver = stable_receiver(call_node.receiver)
+        return current_scope if receiver.nil?
+
+        current_scope.without_indexed_narrowings_for(*receiver)
+      end
+
+      # Companion invalidator for single-hop method-chain
+      # narrowings (ROADMAP § Future cycles — "Method-call
+      # receiver narrowing across stable receivers", B2 from
+      # the slice's design notes). Drops every
+      # `(receiver, *)` chain narrowing rooted at the call's
+      # OUTER stable receiver — matching the ROADMAP's "any
+      # intervening method call against the same receiver"
+      # criterion. A call against `x.last` (the OUTER receiver
+      # is a `CallNode`, not a stable root) does NOT drop
+      # narrowings keyed on `x`, so the worked-site
+      # `x.last << y` pattern correctly preserves the chain
+      # narrowing for any further `x.last` read in the same
+      # body. Always-safe (only forgets; never invents).
+      def invalidate_chain_after_call(call_node:, current_scope:)
+        return current_scope unless call_node.is_a?(Prism::CallNode)
+
+        receiver = stable_receiver(call_node.receiver)
+        return current_scope if receiver.nil?
+
+        current_scope.without_method_chain_narrowings_for(*receiver)
+      end
+    end
+  end
+end

data/lib/rigor/inference/method_dispatcher/iterator_dispatch.rb

@@ -42,9 +42,33 @@ module Rigor
           when :inject, :reduce then inject_block_params(receiver, args)
           when :group_by, :partition then single_element_block_params(receiver)
           when :each_slice, :each_cons then slice_block_params(receiver)
+          when :new then class_new_block_params(receiver, args)
           end
         end
 
+        # `Class.new { |c| … }` and `Class.new(Parent) { |c| … }`
+        # — the block parameter is the freshly-created anonymous
+        # class, statically representable as the parent's singleton
+        # type (the new class inherits every singleton method the
+        # parent exposes, which is what callers use this form to
+        # configure: `c.table_name = …`, `c.attribute :foo`, etc.).
+        # No parent → `singleton(Object)`. RBS would otherwise widen
+        # the block param to bare `Nominal[Class]`, dropping access
+        # to the parent's class-side surface.
+        def class_new_block_params(receiver, args)
+          return nil unless class_metaclass_receiver?(receiver)
+
+          parent = args.first
+          return [Type::Combinator.singleton_of("Object")] if parent.nil?
+          return [parent] if parent.is_a?(Type::Singleton)
+
+          nil
+        end
+
+        def class_metaclass_receiver?(type)
+          type.is_a?(Type::Singleton) && type.class_name == "Class"
+        end
+
         def times_block_params(receiver)
           return nil unless integer_rooted?(receiver)
 

data/lib/rigor/inference/method_dispatcher.rb

@@ -805,9 +805,32 @@ module Rigor
         date_lift = date_new_lift(receiver_type.class_name, arg_types)
         return date_lift if date_lift
 
+        class_new_lift = class_new_lift(receiver_type.class_name, arg_types)
+        return class_new_lift if class_new_lift
+
         Type::Combinator.nominal_of(receiver_type.class_name)
       end
 
+      # `Class.new` and `Class.new(Parent)` create a brand-new
+      # anonymous class. Statically that class is representable as
+      # the parent's singleton type — its singleton-method surface
+      # is the parent's (plus whatever the block defines, which we
+      # do not statically track here), so `Singleton[Parent]` lets
+      # downstream `klass.some_class_method` resolve. No parent →
+      # `singleton(Object)`. Anything else (dynamic parent, more
+      # than one positional, …) falls back to `Nominal[Class]` via
+      # the surrounding `meta_new` tail.
+      def class_new_lift(class_name, arg_types)
+        return nil unless class_name == "Class"
+        return Type::Combinator.singleton_of("Object") if arg_types.empty?
+        return nil unless arg_types.size == 1
+
+        parent = arg_types.first
+        return parent if parent.is_a?(Type::Singleton)
+
+        nil
+      end
+
       # ADR-15 Phase 4b.x — `Ractor.make_shareable` on both the
       # outer Hash and each lambda value. A plain `.freeze` leaves
       # the Procs unshareable; reading `CONSTANT_CONSTRUCTORS[class]`

data/lib/rigor/inference/mutation_widening.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # Widens a local- or instance-variable binding after a call
+    # whose receiver is that variable AND whose method is a known
+    # in-place mutator.
+    #
+    # Closes the **G1 / G2** flow-folding gaps documented at
+    # `docs/notes/20260521-mastodon-cluster4-flow-folding-triage.md`
+    # and queued in [`docs/CURRENT_WORK.md`](../../../docs/CURRENT_WORK.md)
+    # § "Flow-folding". The user-visible symptom they shared was a
+    # spurious `flow.always-truthy-condition` on a `arr.size == N`
+    # / `arr.empty?` / `@arr.empty?` check that follows a loop
+    # body or sibling method that mutates `arr` / `@arr` in place.
+    #
+    # **The mechanism.** When source like
+    #
+    #     arms = [first]                     # arms : Tuple[T]  (size=1)
+    #     while peek_pipe?
+    #       arms << next_arm                 # mutator call on a local
+    #     end
+    #     return arms.first if arms.size == 1
+    #
+    # runs through inference today, the literal `[first]` writes
+    # `arms` as `Tuple[T]`. The shape carrier's `size` folds to
+    # `Constant[1]`. The body's `arms << next_arm` returns a type
+    # for the call expression but does NOT rebind `arms`, so after
+    # the loop `arms` still carries the `Tuple[T]` binding —
+    # `arms.size == 1` constant-folds to `true` and the user sees
+    # a false `flow.always-truthy-condition`.
+    #
+    # The narrowest correct fix is to **widen the receiver binding
+    # at the mutator call site**: replace `arms`'s binding with
+    # `Nominal[Array, [union(elements)]]` so the carrier no longer
+    # carries the literal arity. Inside a loop body, the post-call
+    # body scope then joins with the pre-loop scope through
+    # `join_with_nil_injection` → `Scope#join` (which unions per
+    # name); the resulting union loses size precision, so the
+    # `arms.size` fold returns `Integer` (not `Constant[1]`) and
+    # the diagnostic correctly stays silent.
+    #
+    # The widening is **always type-safe**: it never introduces a
+    # new fact, only forgets a literal-shape fact that is no longer
+    # justified once mutation occurred. It costs only the precise
+    # arity / pair-set the shape carrier was tracking; the underlying
+    # nominal stays exact (`Array` / `Hash`) and element types
+    # stay as a union of what was there.
+    #
+    # **Scope.** This slice addresses:
+    #
+    # - `arr.<mutator>(...)` where `arr` is a local variable.
+    # - `@arr.<mutator>(...)` where `@arr` is an instance variable.
+    #
+    # Out of scope (left for a separate cycle):
+    #
+    # - **`retry` flow edge** (e.g. `tries += 1; retry`). The
+    #   `tries` rebind across `retry` is a flow-edge issue, not a
+    #   call-site mutation issue.
+    # - **Intervening method call invalidates the ivar binding**
+    #   (e.g. `if @performed; perform!; if @performed`). The
+    #   intra-procedural call effect on ivars is a separate
+    #   mutation-effect feature.
+    # - **Read-before-write nil** (e.g. `unless @warning_issued;
+    #   ...; @warning_issued = true`). Requires tracking the
+    #   first-write position; flow-sensitive but orthogonal.
+    # - **Local-variable mutation inside a block body** (e.g.
+    #   `arr = []; xs.each { |x| arr << x }`). Block bodies
+    #   create a child scope; the existing closure-escape model
+    #   only widens outer locals when the block ESCAPES the
+    #   call. An in-place mutator inside a non-escaping block on
+    #   an outer LOCAL does not yet flow back. **Ivar mutations
+    #   inside a block ARE handled** (ivars live in the
+    #   method-body scope, not the block-local scope) — the
+    #   widening fires from inside the block and the new ivar
+    #   binding is visible to the outer scope.
+    #
+    # Those four are documented as "G2 remaining" in
+    # `docs/CURRENT_WORK.md` and are intentionally deferred.
+    module MutationWidening
+      # Array mutators that change either the size or the element
+      # set of a literal-shape carrier (Tuple). Receiver-mutating
+      # methods only — non-mutating siblings (`map` vs `map!`,
+      # `select` vs `select!`) stay precise.
+      #
+      # `<<` and `[]=` are the dominant survey cases; the bang
+      # variants and the size-mutators cover the rest of the
+      # Mastodon cluster-4 G1 catalogue.
+      ARRAY_MUTATORS = %i[
+        << push append prepend unshift concat insert
+        pop shift
+        delete delete_at delete_if reject!
+        clear compact!
+        replace fill []=
+        map! collect! select! filter! keep_if uniq!
+        flatten! sort! sort_by! reverse! rotate! shuffle! slice!
+      ].to_set.freeze
+
+      # Hash mutators that invalidate a `HashShape` carrier. Same
+      # principle as `ARRAY_MUTATORS`: only the receiver-mutating
+      # methods are listed.
+      HASH_MUTATORS = %i[
+        []= store
+        delete delete_if reject! select! filter! keep_if
+        clear compact! merge! update transform_keys! transform_values!
+        replace
+      ].to_set.freeze
+
+      module_function
+
+      # Returns a scope with the call's receiver widened, when the
+      # receiver is a local-/instance-variable read whose current
+      # binding is a literal-shape carrier (`Tuple` / `HashShape`)
+      # AND the call name is a known in-place mutator for that
+      # shape. Returns `current_scope` unchanged otherwise.
+      #
+      # @param call_node     [Prism::CallNode]
+      # @param current_scope [Rigor::Scope]
+      # @return              [Rigor::Scope]
+      def widen_after_call(call_node:, current_scope:)
+        receiver = call_node.receiver
+        return current_scope if receiver.nil?
+
+        case receiver
+        when Prism::LocalVariableReadNode
+          widen_local(call_node.name, receiver.name, current_scope)
+        when Prism::InstanceVariableReadNode
+          widen_ivar(call_node.name, receiver.name, current_scope)
+        else
+          current_scope
+        end
+      end
+
+      # Propagate block-body mutations of outer-scope variables
+      # back into `outer_scope`. Block bodies live in a child
+      # scope; mutations the block body performs on captured
+      # outer LOCALS are otherwise invisible to the post-call
+      # outer scope (ivars are handled correctly already because
+      # they live in the method-body scope, not the block-local
+      # scope).
+      #
+      # Walks the block AST for `<receiver>.<method>(...)` calls
+      # whose receiver is either a `LocalVariableReadNode` with
+      # `depth > 0` (a captured outer local — Prism's `depth`
+      # counts scope hops outward; `depth == 0` means a
+      # block-local) or an `InstanceVariableReadNode` (always
+      # method-scope), and applies `widen_after_call` for each
+      # one against the outer scope. The widening is always safe
+      # — it can only LOSE precision — so blindly propagating is
+      # sound regardless of whether the block actually runs.
+      #
+      # Recurses into nested expression nodes so chained / nested
+      # forms (`arr << f(x); arr << g(y)`, `arr.push(x) if cond`)
+      # are all caught. Does NOT recurse into nested
+      # `Prism::BlockNode`s — each block is processed by its own
+      # `eval_call`.
+      def widen_after_block(call_node:, outer_scope:)
+        block = call_node.block
+        return outer_scope unless block.is_a?(Prism::BlockNode)
+
+        body = block.body
+        return outer_scope if body.nil?
+
+        walk_for_outer_mutations(body, outer_scope)
+      end
+
+      def walk_for_outer_mutations(node, scope)
+        return scope if node.nil?
+
+        scope = widen_for_outer_receiver(node, scope) if node.is_a?(Prism::CallNode)
+
+        # Descend into every child, including nested blocks. The
+        # `LocalVariableReadNode#depth` check inside
+        # `widen_for_outer_receiver` keeps nested-block-locals
+        # from being widened in the outer scope — only references
+        # with `depth >= 1` (true captures of the outer scope's
+        # locals) trigger widening, so descending into nested
+        # blocks is safe and necessary for the hkt_registry-shape
+        # case (an outer collection mutated inside an iterator
+        # block whose body is itself inside another block).
+        node.compact_child_nodes.each do |child|
+          scope = walk_for_outer_mutations(child, scope)
+        end
+        scope
+      end
+
+      def widen_for_outer_receiver(call_node, scope)
+        receiver = call_node.receiver
+        return scope if receiver.nil?
+
+        case receiver
+        when Prism::LocalVariableReadNode
+          return scope if receiver.depth.zero?
+
+          widen_local(call_node.name, receiver.name, scope)
+        when Prism::InstanceVariableReadNode
+          widen_ivar(call_node.name, receiver.name, scope)
+        else
+          scope
+        end
+      end
+
+      def widen_local(method_name, var_name, current_scope)
+        current = current_scope.local(var_name)
+        widened = widen_for_mutator(current, method_name)
+        return current_scope if widened.nil?
+
+        current_scope.with_local(var_name, widened)
+      end
+
+      def widen_ivar(method_name, var_name, current_scope)
+        current = current_scope.ivar(var_name)
+        widened = widen_for_mutator(current, method_name)
+        return current_scope if widened.nil?
+
+        current_scope.with_ivar(var_name, widened)
+      end
+
+      # Returns the widened type for a binding whose receiver is
+      # about to be mutated by `method_name`, or `nil` when no
+      # widening applies (binding is not a literal-shape carrier,
+      # OR the method is not a mutator for that shape, OR the
+      # binding is already a nominal — no precision to lose).
+      def widen_for_mutator(type, method_name)
+        return nil if type.nil?
+
+        case type
+        when Type::Tuple
+          return nil unless ARRAY_MUTATORS.include?(method_name)
+
+          widen_tuple(type)
+        when Type::HashShape
+          return nil unless HASH_MUTATORS.include?(method_name)
+
+          widen_hash_shape(type)
+        end
+      end
+
+      # `Tuple[A, B, C]` → `Nominal[Array, [union(A, B, C)]]`.
+      # An empty tuple has no element evidence, so the widened
+      # form carries `untyped` element bound — matches the
+      # `tuple_to_array` widening already used by `BlockFolding`.
+      def widen_tuple(tuple)
+        element_type =
+          if tuple.elements.empty?
+            Type::Combinator.untyped
+          elsif tuple.elements.size == 1
+            tuple.elements.first
+          else
+            Type::Combinator.union(*tuple.elements)
+          end
+        Type::Combinator.nominal_of("Array", type_args: [element_type])
+      end
+
+      # `HashShape` (closed or open) → `Nominal[Hash, [Kunion,
+      # Vunion]]`. Empty / extra-keys-only shapes degrade to a
+      # fully-untyped Hash.
+      def widen_hash_shape(shape)
+        if shape.pairs.empty?
+          return Type::Combinator.nominal_of("Hash",
+                                             type_args: [Type::Combinator.untyped,
+                                                         Type::Combinator.untyped])
+        end
+
+        key_type = key_union_for(shape.pairs.keys)
+        value_type = Type::Combinator.union(*shape.pairs.values)
+        Type::Combinator.nominal_of("Hash", type_args: [key_type, value_type])
+      end
+
+      # Maps the literal Ruby key set (`Symbol` / `String`) to a
+      # union of the corresponding type carriers. We deliberately
+      # do NOT fold to a `Constant<:k1> | Constant<:k2>` union —
+      # that would be a precision improvement that complicates the
+      # widening contract; the goal here is to LOSE precision, not
+      # to record a new fact set.
+      def key_union_for(keys)
+        kinds = keys.map { |k| k.is_a?(Symbol) ? "Symbol" : "String" }.uniq
+        carriers = kinds.map { |name| Type::Combinator.nominal_of(name) }
+        carriers.size == 1 ? carriers.first : Type::Combinator.union(*carriers)
+      end
+    end
+  end
+end