rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/multi_target_binder.rb

@@ -3,28 +3,64 @@
 require "prism"
 
 require_relative "../type"
+require_relative "optimistic_origin"
+require_relative "method_dispatcher/rbs_dispatch"
 
 module Rigor
   module Inference
     # Slice 5 phase 2 sub-phase 2 destructuring binder.
     #
-    # `Rigor::Inference::MultiTargetBinder` decomposes a tuple-shaped right-hand side type
+    # `Rigor::Inference::MultiTargetBinder` decomposes a tuple- or array-shaped right-hand side type
     # against a Prism multi-target tree and produces a `name -> Rigor::Type` binding map. The
-    # binder is shared between two surfaces:
+    # binder is shared between four surfaces:
     #
     # 1. `Rigor::Inference::StatementEvaluator#eval_multi_write` for the statement-level `a, b =
     #    rhs` form (`Prism::MultiWriteNode`).
     # 2. `Rigor::Inference::BlockParameterBinder` for nested destructuring inside block parameter
     #    lists (`Prism::MultiTargetNode` under `BlockParametersNode#requireds`).
+    # 3. `Rigor::Inference::StatementEvaluator#bind_for_index` for `for a, b in pairs`.
+    # 4. `Rigor::Inference::ScopeIndexer`'s class-ivar pre-pass, for the ivar targets of `@a, @b = rhs`
+    #    (issue #1110), which records {Result#ivars} and drops the marks, as it does for `@x = xs.first`,
+    #    with `soften_slots: false` (see {.bind_marked}).
+    # 5. `Rigor::Inference::StatementEvaluator`'s `case/in` pattern binding (issue #1122), through
+    #    {.decompose_slots}: a pattern binds its names against the same carriers, minus the two
+    #    statement-only properties that method documents.
     #
     # Both Prism nodes share the same `lefts` / `rest` (a `Prism::SplatNode`) / `rights` triple,
     # so the binder treats them uniformly. The binder is pure: it MUST NOT mutate its inputs and
     # MUST return a fresh `Hash` on every call.
     #
-    # The binder threads `Type::Tuple` decompositions when the right-hand side carrier is a
-    # known-arity tuple. Other carriers (`Nominal[Array]`, `Dynamic[Top]`, `Top`, `Bot`, ...)
-    # collapse to `Dynamic[Top]` per slot — Slice 5 phase 2 sub-phase 2 stays conservative on
-    # dynamic-arity right-hand sides until the narrower receiver-shape lattice lands.
+    # Per-carrier rule for the right-hand side:
+    #
+    # - `Type::Tuple` (known arity) decomposes element-wise; see {slot_type} for the softening.
+    # - `Nominal[Array, [T]]`, and a `Refined` / `Difference` over one (`non-empty-array[T]`
+    #   after an `empty?` guard), binds every fixed front/back slot to `T` and a named rest to
+    #   `Array[T]` (issue #1093). A short array pads the fixed slots with `nil` at runtime, so
+    #   `T` is the same optimistic read `Array#[]` / `Array#first` get past core RBS's
+    #   `%a{implicitly-returns-nil}`: the binder reports those names in {Result#optimistic}, and
+    #   every caller that applies the bindings to a scope records them through
+    #   `Scope#with_optimistic_local` ({Result#apply_to}) so the ADR-101 branch elision
+    #   declines on them. A nested target under an optimistic slot inherits the mark (`nil`
+    #   destructures to `nil` for every inner name); the rest never carries it.
+    # - A `Type::Union` distributes (issue #1094): each member decomposes on its own against the
+    #   same target tree, and each name binds the join of its per-member types. A member that binds
+    #   a name to `Dynamic[Top]` — every name, for a member no rule here decomposes — makes that
+    #   name `Dynamic[Top]` for the whole union rather than dropping out of the join. A member that
+    #   binds a name to bare `nil` while another binds a value drops out of that name's join, and
+    #   the name is marked optimistic: the per-slot softening of {slot_type}, applied across
+    #   members (see {join_member_bindings}). So `a, b = ints[1..]` (`Array[Integer] | nil`) binds
+    #   `Integer` to each slot, marked, exactly as a short `ints` would. A name is also optimistic
+    #   when any member marked it, the rule `Scope#join` applies to the same mark at a merge.
+    # - A value that provably has no implicit `to_ary` conversion
+    #   ({MethodDispatcher::RbsDispatch.array_conversion_free?}: `Integer`, `String`, `Hash`,
+    #   `nil`, ... and RBS-known classes whose ancestry neither defines `to_ary` nor overrides
+    #   `method_missing` / `respond_to_missing?`) is what Ruby wraps as `[rhs]`, so it decomposes
+    #   as that one-element `Tuple` (issue #1094): `a, b = 1` binds `1` and `nil`. The wrap is
+    #   exact rather than a bet, so it adds no mark.
+    # - Everything else — raw `Array`, `Array[Dynamic[top]]`, `Dynamic[Array[T]]` (whose static
+    #   facet must not surface as a bare `T`), a value that may convert (`SimpleDelegator`, a
+    #   Ruby-source class, a module, `Object`), `Top`, `Bot` — collapses to `Dynamic[Top]` per
+    #   slot.
     #
     # Targets the binder recognises:
     #
@@ -37,67 +73,299 @@ module Rigor
     #   same observable semantics (binding a fresh local in the block-entry scope).
     # - `Prism::MultiTargetNode` — recurses with the slot's type as the new right-hand side.
     # - `Prism::SplatNode` (used for `rest`) — its `expression` MUST be a
-    #   `Prism::LocalVariableTargetNode` or a `Prism::RequiredParameterNode` to be observable;
-    #   an anonymous `*` splat or a non-local target is skipped.
+    #   `Prism::LocalVariableTargetNode`, a `Prism::RequiredParameterNode`, a
+    #   `Prism::InstanceVariableTargetNode` or a `Prism::IndexTargetNode` to be observable; an
+    #   anonymous `*` splat or any other target is skipped.
+    # - `Prism::InstanceVariableTargetNode` (issue #1110), as a fixed slot, a rest
+    #   (`*@rest`), or inside a nested target. It decomposes by the same carrier rules as a
+    #   local and is reported apart, in {Result#ivars} / {Result#optimistic_ivars}, so a caller
+    #   that threads only locals never sees it. The binder keys it internally by its `:@name`,
+    #   which no local name can collide with.
+    # - `Prism::IndexTargetNode` (`h[:a], x = rhs`), in the same three positions. It binds no
+    #   name: it stores its slot through `[]=` on its receiver. The binder reports the value it
+    #   stores in {Result#index_targets}, keyed by the target node itself, so
+    #   `StatementEvaluator#eval_multi_write` and `#bind_for_index` (`for h[:a], w in pairs`) can
+    #   widen the receiver's literal shape with that value as content evidence, exactly as a plain
+    #   `h[:a] = 1` does. It carries no optimistic mark: there is no binding for one to qualify.
+    #   Its slot is softened as a local's is; `eval_multi_write` documents why that stays honest
+    #   without the mark.
     #
-    # Other target kinds (`InstanceVariableTargetNode`, `ConstantTargetNode`,
-    # `IndexTargetNode`, `CallTargetNode`, `ConstantPathTargetNode`, `ImplicitRestNode`, ...)
-    # MUST be silently skipped: they have no observable contribution to the local-variable scope
-    # the StatementEvaluator threads.
+    # Other target kinds (`ClassVariableTargetNode`, `GlobalVariableTargetNode`,
+    # `ConstantTargetNode`, `CallTargetNode`, `ConstantPathTargetNode`, `ImplicitRestNode`, ...)
+    # MUST be silently skipped: they have no observable contribution to the scope the
+    # StatementEvaluator threads.
     #
     # See docs/internal-spec/inference-engine.md for the binding contract and
     # docs/adr/4-type-inference-engine.md for the slice rationale.
     module MultiTargetBinder
+      NO_BINDINGS = {}.freeze
+      NO_NAMES = [].freeze
+      private_constant :NO_BINDINGS, :NO_NAMES
+
+      # `types` is the local `name -> Rigor::Type` map {.bind} returns; `optimistic` the frozen list
+      # of local names whose nil-freeness is the short-array bet described in the module comment.
+      # `ivars` / `optimistic_ivars` are the same pair for instance-variable targets.
+      # `index_targets` maps each `Prism::IndexTargetNode` to the value it stores; {#apply_to}
+      # binds nothing for it.
+      Result = Data.define(:types, :optimistic, :ivars, :optimistic_ivars, :index_targets) do
+        def initialize(types:, optimistic:, ivars: NO_BINDINGS, optimistic_ivars: NO_NAMES,
+                       index_targets: NO_BINDINGS)
+          super
+        end
+
+        # Binds every name into `scope` and records the optimistic mark after the binding, since
+        # `Scope#with_local` / `Scope#with_ivar` drop any mark the name carried before. `miss` is what
+        # each marked slot answers on a miss (issue #1302): `nil` for every mark the binder makes itself —
+        # a short array pads with `nil`, and a `nil` destructures to `nil` — so only a caller whose
+        # right-hand side a miss can make something else passes another answer
+        # ({OptimisticOrigin.destructuring_miss}).
+        def apply_to(scope, miss: nil)
+          bound = types.reduce(scope) { |acc, (name, type)| acc.with_local(name, type) }
+          bound = ivars.reduce(bound) { |acc, (name, type)| acc.with_ivar(name, type) }
+          bound = optimistic.reduce(bound) do |acc, name|
+            acc.with_optimistic_local(name, OptimisticOrigin::IMPLICITLY_RETURNS_NIL, miss: miss)
+          end
+          optimistic_ivars.reduce(bound) do |acc, name|
+            acc.with_optimistic_ivar(name, OptimisticOrigin::IMPLICITLY_RETURNS_NIL, miss: miss)
+          end
+        end
+      end
+
       module_function
 
-      # @param target_node [Prism::MultiWriteNode, Prism::MultiTargetNode]
-      # @param rhs_type [Rigor::Type] type of the right-hand side
-      # @return [Hash{Symbol => Rigor::Type}]
-      def bind(target_node, rhs_type)
+      # @param rhs_type — type of the right-hand side
+      # @param scope — the scope the destructure is evaluated in, which answers the `to_ary`
+      #   question for a class outside the core list; without one only the core list wraps.
+      def bind(target_node, rhs_type, scope: nil)
+        bind_marked(target_node, rhs_type, scope: scope).types
+      end
+
+      # @param optimistic — whether `rhs_type` itself is an optimistic slot of an enclosing
+      #   decomposition (a block's `|(g, h)|` fed from an auto-splatted `Array[T]`) or an
+      #   optimistically nil-free value (`k, v = xs.first`), in which case every name bound under it
+      #   inherits the mark. It may instead be the per-element Array
+      #   {OptimisticOrigin.destructuring_marks} builds for a literal right-hand side
+      #   (`x, y = xs.first, 1`), which marks the names under each fixed slot by that slot's element.
+      # @param soften_slots — false keeps a present `X | nil` tuple slot and a union member's bare
+      #   `nil` in the binding instead of applying the ADR-57 softening of {slot_type} /
+      #   {join_member_bindings}. That softening is only honest together with the optimistic mark
+      #   it records, so a consumer that drops the marks (the class-ivar seed, issue #1110) turns it
+      #   off; the `Array[T]` bet is unaffected, matching what `@x = xs.first` records.
+      def bind_marked(target_node, rhs_type, optimistic: false, scope: nil, soften_slots: true)
         bindings = {}
-        visit(target_node, rhs_type, bindings)
-        bindings
+        marked = []
+        visit(target_node, rhs_type, optimistic, bindings, marked, [scope, soften_slots])
+        split_result(bindings, marked)
+      end
+
+      # The per-slot types of a positional pattern (`in [i, s]`, `in [*pre, m, *post]`), sharing
+      # every carrier rule {.bind_marked} applies to a multi-write target except two statement-only
+      # properties (issue #1122):
+      #
+      # - the multi-assign `[rhs]` wrap is NOT applied. `a, b = 1` binds `a` to `1` because Ruby wraps
+      #   a right-hand side with no implicit `to_ary`; an array pattern instead matches through the
+      #   subject's `deconstruct` / `to_ary`, and a subject with neither raises
+      #   `NoMatchingPatternError` — no body is reached, so binding `1` there would type dead code.
+      # - no optimistic mark is reported. The ADR-101 short-array bet exists because a SHORT
+      #   right-hand side pads the fixed slots with `nil`; a pattern that matched has every fixed slot
+      #   it named, so there is nothing to bet on and `Result#optimistic` has no counterpart here.
+      #
+      # A `Type::Union` is the caller's to distribute: a pattern matches SOME member, and only the
+      # caller can tell which members can match it at all. Returns `[fronts, rest_type, backs]`, with
+      # every carrier no rule decomposes answering `Dynamic[Top]` per slot — the floor.
+      def decompose_slots(rhs_type, front_count:, back_count:, rest_present:, scope: nil, soften_slots: true)
+        fronts, rest_type, backs, = decompose(
+          rhs_type, front_count, back_count, rest_present: rest_present,
+                                             context: [scope, soften_slots], wrap_single: false
+        )
+        [fronts, rest_type, backs]
+      end
+
+      # The `T` of an `Array[T]` carrier the binder may decompose, or nil. Declines raw `Array`
+      # and an untyped / top element, which bind `Dynamic[Top]` per slot as before, and every
+      # `Dynamic` wrapper: `Dynamic[Array[T]]` is gradual, and projecting its static facet would
+      # hand the slot a bare `T` that licenses the negative rules (ADR-5). Shared with
+      # {BlockParameterBinder}'s auto-splat so both surfaces accept the same carriers.
+      def array_element_type(type)
+        case type
+        when Type::Nominal
+          return nil unless type.class_name == "Array" && type.type_args.size == 1
+
+          element = type.type_args.first
+          element.is_a?(Type::Dynamic) || element.is_a?(Type::Top) ? nil : element
+        when Type::Refined, Type::Difference
+          array_element_type(type.base)
+        end
+      end
+
+      # The class whose instances `type` describes, for the `to_ary` question, or nil when `type`
+      # names no single class: `Dynamic`, `Top`, `Singleton`, `Intersection` and the rest decline.
+      # A union never reaches here; the binder distributes it first.
+      def conversion_class_name(type)
+        case type
+        when Type::Constant then type.value.class.name
+        when Type::Nominal then type.class_name
+        when Type::HashShape then "Hash"
+        when Type::IntegerRange then "Integer"
+        when Type::Refined, Type::Difference then conversion_class_name(type.base)
+        end
       end
 
       class << self
         private
 
-        def visit(node, rhs_type, bindings)
+        # Partitions the walk's single map: an ivar name carries its `@` sigil, which a local name
+        # never does, and an index target is keyed by its node rather than by a name.
+        def split_result(bindings, marked)
+          return Result.new(types: bindings, optimistic: marked.freeze) if bindings.each_key.all? { |k| local_key?(k) }
+
+          grouped = bindings.group_by { |key, _| key_kind(key) }.transform_values(&:to_h)
+          ivar_marked, local_marked = marked.partition { |name| key_kind(name) == :ivar }
+          Result.new(types: grouped.fetch(:local, {}), optimistic: local_marked.freeze,
+                     ivars: grouped.fetch(:ivar, NO_BINDINGS), optimistic_ivars: ivar_marked.freeze,
+                     index_targets: grouped.fetch(:index, NO_BINDINGS))
+        end
+
+        def local_key?(key) = key.is_a?(Symbol) && !key.start_with?("@")
+
+        def key_kind(key)
+          return :index unless key.is_a?(Symbol)
+
+          key.start_with?("@") ? :ivar : :local
+        end
+
+        # `context` is the `[scope, soften_slots]` pair every step of the walk shares.
+        def visit(node, rhs_type, optimistic, bindings, marked, context)
+          if rhs_type.is_a?(Type::Union)
+            return visit_union(node, rhs_type.members, optimistic, bindings, marked, context)
+          end
+
           lefts = node.lefts || []
           rest = node.rest
           rights = node.rights || []
+          rest_present = !rest.nil?
 
-          fronts, rest_type, backs = decompose(rhs_type, lefts.size, rights.size, rest_present: !rest.nil?)
-          lefts.each_with_index { |t, i| bind_target(t, fronts[i], bindings) }
-          bind_rest_target(rest, rest_type, bindings) if rest
-          rights.each_with_index { |t, i| bind_target(t, backs[i], bindings) }
+          fronts, rest_type, backs, slots_optimistic =
+            decompose(rhs_type, lefts.size, rights.size, rest_present: rest_present, context: context)
+          rest_type = arity_free_rest(rest_type) if optimistic == true
+          front_marks, back_marks =
+            slot_marks(optimistic, slots_optimistic, rhs_type, [lefts.size, rights.size], rest_present: rest_present)
+          lefts.each_with_index { |t, i| bind_target(t, fronts[i], front_marks[i], bindings, marked, context) }
+          bind_rest_target(rest, rest_type, bindings, marked) if rest
+          rights.each_with_index { |t, i| bind_target(t, backs[i], back_marks[i], bindings, marked, context) }
+        end
+
+        # The `[front_marks, back_marks]` pair a visit hands its fixed slots. A boolean `optimistic`
+        # applies to every slot, as does the decomposition's own short-array bet (`fallback`, the
+        # issue #1093 `Array[T]` mark). A per-element Array applies only to the `Type::Tuple` a literal
+        # right-hand side types as, of the same arity, and each slot picks its element at the offset
+        # {decompose_tuple} reads ({slot_offsets}); any other carrier falls back to `fallback`, and a
+        # slot past the literal's end binds an exact `nil` that no mark qualifies.
+        def slot_marks(optimistic, fallback, rhs_type, (front_count, back_count), rest_present:)
+          literal = optimistic.is_a?(Array) && rhs_type.is_a?(Type::Tuple) && rhs_type.elements.size == optimistic.size
+          uniform = optimistic.is_a?(Array) ? fallback : optimistic || fallback
+          return [[uniform] * front_count, [uniform] * back_count] unless literal
+
+          slot_offsets(optimistic.size, front_count, back_count, rest_present: rest_present)
+            .map { |offsets| offsets.map { |i| optimistic.fetch(i, false) } }
+        end
+
+        # Every member walks the same target tree, so each binds the same names; the first member's
+        # key order is the declaration order.
+        def visit_union(node, members, optimistic, bindings, marked, context)
+          walks = members.map do |member|
+            member_bindings = {}
+            member_marked = []
+            visit(node, member, optimistic, member_bindings, member_marked, context)
+            [member_bindings, member_marked]
+          end
+          walks.first.first.each_key do |name|
+            types = walks.map { |member_bindings, _| member_bindings[name] }
+            joined, softened = join_member_bindings(types, context.last)
+            mark = softened || walks.any? { |_, member_marked| member_marked.include?(name) }
+            bind_name(name, joined, mark, bindings, marked)
+          end
+        end
+
+        # Returns `[type, softened]`. `Dynamic[Top]` from any member is the whole answer: the join
+        # must not let a decomposable member's precise type stand for a member nothing is known
+        # about. A member that binds the name to bare `nil` — a `nil` slot, a slot past a short
+        # member, or a `nil` member wrapped as `[nil]` — is left out of the join when another member
+        # binds a value, and `softened` reports it so the caller marks the name optimistic. This is
+        # {slot_type}'s ADR-57 softening across members: which member arrived is correlated with the
+        # other slots (`k, v = hash.find { ... }; v.x if k`, `status, value = ok ? [:ok, v] : [:err]`),
+        # and a per-slot `T | nil` fires `call.possible-nil-receiver` on the guarded read.
+        def join_member_bindings(types, soften_slots)
+          untyped = Type::Combinator.untyped
+          return [untyped, false] if types.any? { |type| type == untyped }
+
+          firm = types.reject { |type| nil_literal?(type) }
+          return [Type::Combinator.union(*types), false] if !soften_slots || firm.empty? || firm.size == types.size
+
+          [Type::Combinator.union(*firm), true]
         end
 
         # Decomposes the right-hand side type into the per-slot types. Returns a `[fronts,
-        # rest_type, backs]` triple, with `fronts` and `backs` each an ordered array of length
-        # `front_count`/`back_count`, and `rest_type` either a `Rigor::Type` (when
-        # `rest_present:` is true) or `nil`.
-        def decompose(rhs_type, front_count, back_count, rest_present:)
+        # rest_type, backs, optimistic]` quadruple, with `fronts` and `backs` each an ordered
+        # array of length `front_count`/`back_count`, `rest_type` either a `Rigor::Type` (when
+        # `rest_present:` is true) or `nil`, and `optimistic` true when the fixed slots are the
+        # short-array bet rather than known elements.
+        def decompose(rhs_type, front_count, back_count, rest_present:, context:, wrap_single: true)
+          scope, soften = context
           if rhs_type.is_a?(Type::Tuple)
-            decompose_tuple(rhs_type, front_count, back_count, rest_present: rest_present)
+            [*decompose_tuple(rhs_type, front_count, back_count, rest_present: rest_present, soften: soften), false]
+          elsif (element = array_element_type(rhs_type))
+            [*decompose_array(element, front_count, back_count, rest_present: rest_present), true]
+          elsif wrap_single && wraps_as_single_element?(rhs_type, scope)
+            wrapped = Type::Combinator.tuple_of(rhs_type)
+            [*decompose_tuple(wrapped, front_count, back_count, rest_present: rest_present, soften: soften), false]
           else
-            decompose_default(front_count, back_count, rest_present: rest_present)
+            [*decompose_default(front_count, back_count, rest_present: rest_present), false]
           end
         end
 
-        def decompose_tuple(tuple, front_count, back_count, rest_present:)
+        # Ruby's `[rhs]` wrap for a value with no implicit `to_ary`; see the module comment.
+        def wraps_as_single_element?(rhs_type, scope)
+          class_name = conversion_class_name(rhs_type)
+          !class_name.nil? && MethodDispatcher::RbsDispatch.array_conversion_free?(class_name, scope)
+        end
+
+        # Under an inherited mark the whole right-hand side may be the `nil` a short outer array padded in, and
+        # `(p, *q) = nil` binds `q = []`. A Tuple rest would claim the middle elements are present
+        # (`q.first.nil?` folding to `false`), so it widens to `Array[union of the middle]`, which admits the
+        # empty array; an empty middle has no element type to offer and stays `Array[Dynamic[top]]`.
+        def arity_free_rest(rest_type)
+          return rest_type unless rest_type.is_a?(Type::Tuple)
+
+          element = rest_type.elements.empty? ? Type::Combinator.untyped : Type::Combinator.union(*rest_type.elements)
+          Type::Combinator.nominal_of("Array", type_args: [element])
+        end
+
+        def decompose_array(element, front_count, back_count, rest_present:)
+          [
+            Array.new(front_count) { element },
+            rest_present ? Type::Combinator.nominal_of("Array", type_args: [element]) : nil,
+            Array.new(back_count) { element }
+          ]
+        end
+
+        def decompose_tuple(tuple, front_count, back_count, rest_present:, soften:)
           elements = tuple.elements
-          fronts = Array.new(front_count) { |i| slot_type(elements, i) }
-          if rest_present
-            middle_end = [elements.size - back_count, front_count].max
-            middle = elements[front_count...middle_end] || []
-            rest_type = Type::Combinator.tuple_of(*middle)
-            backs = Array.new(back_count) { |i| slot_type(elements, middle_end + i) }
-          else
-            rest_type = nil
-            backs = Array.new(back_count) { |i| slot_type(elements, front_count + i) }
-          end
-          [fronts, rest_type, backs]
+          fronts, backs = slot_offsets(elements.size, front_count, back_count, rest_present: rest_present)
+                          .map { |offsets| offsets.map { |i| slot_type(elements, i, soften) } }
+          # The end is clamped at the fronts, as {slot_offsets} clamps the backs: an unclamped negative end
+          # (more back slots than elements) would count from the end instead. A range starting past the end
+          # slices to `nil`.
+          middle = elements[front_count...[elements.size - back_count, front_count].max] || []
+          [fronts, rest_present ? Type::Combinator.tuple_of(*middle) : nil, backs]
+        end
+
+        # The element offsets a `[fronts, backs]` pair of fixed slots reads out of `size` elements: the
+        # back slots follow the middle a rest absorbs, and follow the fronts directly without one. An
+        # offset past `size` is a slot the source is too short to fill.
+        def slot_offsets(size, front_count, back_count, rest_present:)
+          back_start = rest_present ? [size - back_count, front_count].max : front_count
+          [Array.new(front_count) { |i| i }, Array.new(back_count) { |i| back_start + i }]
         end
 
         # The per-slot type for index `i` of a tuple decomposition, FP-safely softened: a
@@ -118,11 +386,11 @@ module Rigor
         # outranks the worst-case per-slot reading, so we drop the `nil` from a destructured slot
         # and keep the non-`nil` constituent (a bare `nil` slot stays `nil` — there is nothing to
         # soften). A pure non-optional element keeps its precise type unchanged.
-        def slot_type(elements, index)
+        def slot_type(elements, index, soften)
           element = elements[index]
           return Type::Combinator.constant_of(nil) if element.nil?
 
-          soften_optional_slot(element)
+          soften ? soften_optional_slot(element) : element
         end
 
         def soften_optional_slot(element)
@@ -147,24 +415,42 @@ module Rigor
           ]
         end
 
-        def bind_target(target, type, bindings)
-          case target
-          when Prism::LocalVariableTargetNode, Prism::RequiredParameterNode
-            bindings[target.name] = type
-          when Prism::MultiTargetNode
-            visit(target, type, bindings)
-          end
+        # A per-element Array mark reaches a name only through a nested target: a name bound to a
+        # whole literal array holds an Array, which is never `nil`. Nor does any mark reach a name bound
+        # to an exact `nil` — a slot past a Tuple's end or a wrap's empty slot — which is `nil` whether
+        # or not the source missed, so the mark could only withhold an honest verdict.
+        def bind_target(target, type, optimistic, bindings, marked, context)
+          return visit(target, type, optimistic, bindings, marked, context) if target.is_a?(Prism::MultiTargetNode)
+
+          key = binding_key(target)
+          bind_name(key, type, optimistic == true && !nil_literal?(type), bindings, marked) if key
         end
 
-        def bind_rest_target(splat_node, type, bindings)
+        # The rest is an `Array` even when the right-hand side is short, so it is never marked.
+        def bind_rest_target(splat_node, type, bindings, marked)
           return unless splat_node.is_a?(Prism::SplatNode)
 
-          expression = splat_node.expression
-          case expression
-          when Prism::LocalVariableTargetNode, Prism::RequiredParameterNode
-            bindings[expression.name] = type
+          key = binding_key(splat_node.expression)
+          bind_name(key, type, false, bindings, marked) if key
+        end
+
+        # A named target's name, an index target's node (it binds no name, see {bind_name}), or nil for
+        # a target that contributes nothing to the scope.
+        def binding_key(target)
+          case target
+          when Prism::LocalVariableTargetNode, Prism::RequiredParameterNode, Prism::InstanceVariableTargetNode
+            target.name
+          when Prism::IndexTargetNode then target
           end
         end
+
+        # A later binding of the same name (`a, a = ints`) wins, mark included. `name` is the
+        # target node for an index target, which binds no name and so is never marked.
+        def bind_name(name, type, optimistic, bindings, marked)
+          bindings[name] = type
+          marked.delete(name)
+          marked << name if optimistic && name.is_a?(Symbol)
+        end
       end
     end
   end

data/lib/rigor/inference/mutation_rejoin.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "content_join"
+require_relative "rewrite_mutation"
+
+module Rigor
+  module Inference
+    # The re-join half of the mutation widening (issue #580): what happens to the SECOND and later
+    # content mutations of one collection, once {MutationWidening} has already replaced the literal
+    # carrier with a `Nominal`.
+    #
+    # Split out of {MutationWidening} because it answers a different question. That module decides
+    # what a mutation FALSIFIES about a literal shape; this one decides when a carrier is still open
+    # enough to LEARN from, which is a provenance question the type system has no field for and this
+    # file answers off the carrier itself.
+    module MutationRejoin
+      module_function
+
+      # Re-opens a carrier this seam already widened once, so the SECOND and later stores into the
+      # same collection are seen (issue #580).
+      #
+      # Before this arm the widening was a one-way door: the first content mutation replaced the
+      # literal `Tuple` / `HashShape` with a `Nominal`, `widen_for_mutator` had no `Nominal` arm, and
+      # `a = []; a.push(1); a.push("s")` closed at `Array[Integer | Dynamic[top]]` with the `String`
+      # arm simply absent. The `Dynamic` arm kept that from being a WRONG answer — nothing folds and
+      # nothing dispatches off a union carrying it — but the carrier still did not say what the
+      # program holds, and every precision lever that would eventually take the gradual arm off had
+      # to inherit the missing store.
+      #
+      # `nil` when the re-join changed nothing, so a non-adder (`pop`, `sort!`) on an already-widened
+      # carrier does not rebind the binding at all: a rebind drops the per-slot narrowings `with_local`
+      # keys to the old value, and paying that for an identical type is a straight loss.
+      def widen_nominal(nominal, method_name, values: :widen, arg_types: MutationWidening::NO_ARG_TYPES)
+        return nil unless regrowable_carrier?(nominal)
+
+        pre_state = values == :widen ? value_pin_widened_args(nominal) : nominal
+        rejoined =
+          case nominal.class_name
+          when "Array"
+            return nil unless MutationWidening::ARRAY_MUTATORS.include?(method_name)
+
+            MutationWidening.join_added_elements(pre_state, method_name, arg_types,
+                                                 pinned_evidence(ContentJoin.collection_element_types(pre_state)))
+          when "Hash"
+            return nil unless MutationWidening::HASH_MUTATORS.include?(method_name)
+
+            seed_keys, seed_values = ContentJoin.hash_shape_key_values(pre_state)
+            MutationWidening.join_added_pairs(pre_state, method_name, arg_types,
+                                              [pinned_evidence(seed_keys), pinned_evidence(seed_values)])
+          end
+        # The arm lands after the precise parameters are restored: a rewriter falsifies a proven side too
+        # (`Hash.new(0)` under `transform_values!(&:to_s)` holds Strings), which an adder's one store cannot.
+        rejoined = RewriteMutation.arm(keep_precise_parameters(pre_state, rejoined), method_name)
+        rejoined == nominal ? nil : rejoined
+      end
+
+      # Re-grows only the parameters that were already gradual, restoring every other one.
+      #
+      # {#regrowable_carrier?} asks the carrier as a whole, but a `Hash` has two parameters and they
+      # can disagree: `Hash.new(0)` is `Hash[Dynamic[top], Integer]` — an open key side over a value
+      # side the default-arg fold PROVED. Re-joining both put the gradual floor on the value side and
+      # cost the counter idiom (`h = Hash.new(0); h[:x] += 1; h[:x]`) its `Integer` for a
+      # `Dynamic[top] | Integer`, a precision loss for evidence the key side alone was missing.
+      #
+      # The restored side comes from the pin-widened pre-state rather than the original carrier, so a
+      # slot-rewriting mutator still falsifies the pinning it falsifies.
+      def keep_precise_parameters(pre_state, rejoined)
+        return rejoined unless rejoined.is_a?(Type::Nominal) && rejoined.type_args.size == pre_state.type_args.size
+
+        args = pre_state.type_args.each_with_index.map do |arg, i|
+          gradual_parameter?(arg) ? rejoined.type_args[i] : arg
+        end
+        Type::Combinator.nominal_of(rejoined.class_name, type_args: args)
+      end
+
+      # The class claim a re-opened carrier still makes, for {ContentJoin.admissible_evidence} to gate
+      # the added members against.
+      #
+      # It is the carrier's VALUE-PINNED arms and nothing else, because pinning is the only trace a
+      # literal seed's own elements leave once the carrier is nominal. Reading the whole element list
+      # instead gets both ends wrong. {ContentJoin.admissible_evidence} answers "everything is
+      # admissible" for a seed carrying a `Dynamic`, and a re-opened carrier ALWAYS carries one — its
+      # own gradual floor — so the gate would be off exactly where it is needed: haml's
+      # `temple = [:multi]` grew an `Array[…]` arm past its hand-written `-> Array[:multi]` and brought
+      # the #561 `def.return-type-mismatch` back. Gating on the full list is the opposite error — after
+      # `a = []; a.push(1)` the carrier reads `Array[Integer | Dynamic[top]]`, and a class set of
+      # `{Integer}` floors the `"s"` the next line stores, which is the whole answer this issue is
+      # about. The pinning tells the two apart: `:multi` is a claim the author's literal made, `Integer`
+      # is this seam's own join talking back to itself.
+      #
+      # No pinned arm means no claim to contradict — an empty-seeded accumulator — and the added
+      # evidence is admitted as itself.
+      def pinned_evidence(members)
+        members.flat_map { |m| ContentJoin.union_members(m) }.grep(Type::Constant)
+      end
+
+      # Which nominals may re-grow — the FP boundary this whole issue turns on, read off the carrier
+      # itself rather than out of a side table.
+      #
+      # A carrier that already carries a gradual arm on the parameter the mutation feeds is one this
+      # seam (or a declaration) has already declared open. Growing it is free of the #561 blast
+      # radius by construction: adding a member to a union that already contains `Dynamic[top]`
+      # cannot make the union reject a declared type it accepted, cannot manufacture a constant fold
+      # (a union carrying `Dynamic` never folds), and cannot make a dispatch that was quiet fire.
+      # What it CAN do is stop dropping evidence — which is the whole point.
+      #
+      # A PRECISE nominal is refused, and that is exactly the case the issue names: haml's
+      # hand-written `-> Array[:multi]`, or an `Array[Symbol]` an RBS signature declares. Its element
+      # set is a claim somebody made about the collection, not a residue of this seam's own
+      # one-store guesswork, and joining a foreign member into it is what drew eight
+      # `def.return-type-mismatch` on correct code (PR #561). The seed-admissibility gate in
+      # {ContentJoin.admissible_evidence} stays the guard for everything that does get through.
+      #
+      # This is a superset of "mutation-widened": a DECLARED `Array[untyped]` or
+      # `Array[Integer | untyped]` matches too. Deliberate — the soundness argument above is about
+      # the carrier being open, not about who opened it, and a declared gradual arm is the author
+      # saying the collection may hold anything. Distinguishing the two needs provenance travelling
+      # WITH the value (a field on `Type::Nominal`, reopening structural equality, `Marshal`, and the
+      # cache schema); nothing on this axis needs it yet.
+      def regrowable_carrier?(nominal)
+        return false unless %w[Array Hash].include?(nominal.class_name)
+
+        nominal.type_args.any? { |arg| gradual_parameter?(arg) }
+      end
+
+      def gradual_parameter?(type)
+        ContentJoin.union_members(type).any?(Type::Dynamic)
+      end
+
+      # The value-rewriting counterpart of {MutationWidening.widen_tuple}'s `values: :widen`. A mutator that lands a
+      # new value in an EXISTING slot falsifies that slot's pinning on a re-opened carrier exactly as
+      # it does on a literal one, so `d = [:multi]; d << x; d[0] = "s"` must not keep reading `:multi`
+      # back out of slot 0.
+      def value_pin_widened_args(nominal)
+        Type::Combinator.nominal_of(nominal.class_name,
+                                    type_args: nominal.type_args.map { |a| Type::Combinator.widen_value_pinned(a) })
+      end
+
+      # Rebinds `name` to the widened carrier, carrying across what a re-join must not lose.
+      def rebind(scope, builder, name, widened, pre_state:, kind:)
+        rebound = scope.public_send(builder, name, widened)
+        pre_state.is_a?(Type::Nominal) ? carry_slot_narrowings(rebound, scope, kind, name) : rebound
+      end
+
+      # Re-installs the per-slot `receiver[key] ||= default` narrowings that rebinding the receiver
+      # drops.
+      #
+      # `Scope#with_local` drops them because a rebind normally means a DIFFERENT object, and the
+      # slot's non-nil guarantee was about the old one. A re-join (issue #580) is the opposite: the
+      # binding still names the same object, and only the summary of what it holds grew. Before the
+      # `Nominal` arm existed the second store into an already-widened carrier rebound nothing at
+      # all, so the narrowing survived by accident — Redmine's `params[:f] ||= []` then
+      # `params[:op] ||= {}` idiom lost `:f`'s narrowing the moment `:op` re-joined, and the next
+      # `params[:f] << :status` dispatched on nil again. Carrying them keeps the re-join's scope
+      # effect to the one thing it actually learned.
+      #
+      # The call recording its OWN key runs after the widening (`eval_index_or_write` orders it that
+      # way deliberately), so a carried entry never shadows a fresher one for the same slot.
+      # Method-chain narrowings are deliberately NOT carried: `x.last` is a claim about a position a
+      # content mutation really can move.
+      def carry_slot_narrowings(rebound, pre_scope, kind, name)
+        pre_scope.indexed_narrowings.reduce(rebound) do |acc, (key, type)|
+          next acc unless key.receiver_kind == kind && key.receiver_name == name.to_sym
+
+          acc.with_indexed_narrowing(key.receiver_kind, key.receiver_name, key.key, type)
+        end
+      end
+    end
+  end
+end