rigortype 0.3.8 → 0.3.9

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

@@ -21,10 +21,13 @@ module Rigor
         module_function
 
         def reorder(overloads, self_type:, environment:)
-          return overloads if environment.nil?
+          return overloads if environment.nil? || overloads.size <= 1
 
           self_class_name = self_type_class_name(self_type)
           return overloads if self_class_name.nil?
+          # A list with no affinity arm behind a non-affinity arm is already in order -- the common case,
+          # answered without the partition's three arrays (#775).
+          return overloads unless out_of_order?(overloads, self_class_name, environment)
 
           affinity, other = overloads.partition do |mt|
             overload_param_classes_in_ancestry?(mt, self_class_name, environment)
@@ -41,6 +44,19 @@ module Rigor
             end
           end
 
+          # True when some affinity arm follows a non-affinity arm, i.e. the stable partition would move it.
+          def out_of_order?(overloads, self_class_name, environment)
+            other_seen = false
+            overloads.each do |mt|
+              if overload_param_classes_in_ancestry?(mt, self_class_name, environment)
+                return true if other_seen
+              else
+                other_seen = true
+              end
+            end
+            false
+          end
+
           # `RBS::Types::UntypedFunction` (a `(?)` method type, e.g. core's `Proc#call`) declares no
           # parameters and exposes none of the per-arity accessors. It has no param classes to compare
           # against the receiver, so it carries no affinity either way.
@@ -48,10 +64,15 @@ module Rigor
             fun = method_type.type
             return false unless fun.respond_to?(:required_positionals)
 
-            params = fun.required_positionals + fun.optional_positionals + fun.trailing_positionals
-            return false if params.empty?
+            required = fun.required_positionals
+            optional = fun.optional_positionals
+            trailing = fun.trailing_positionals
+            return false if required.empty? && optional.empty? && trailing.empty?
 
-            params.all? { |param| param_class_in_ancestry?(param.type, self_class_name, environment) }
+            # The three lists are checked in place rather than concatenated (#775).
+            required.all? { |param| param_class_in_ancestry?(param.type, self_class_name, environment) } &&
+              optional.all? { |param| param_class_in_ancestry?(param.type, self_class_name, environment) } &&
+              trailing.all? { |param| param_class_in_ancestry?(param.type, self_class_name, environment) }
           end
 
           # Walks Optional and Union one level so `(Numeric?)` and `(Integer | Float)` still classify when

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

@@ -58,7 +58,6 @@ module Rigor
         CONSTANT_FOLD_BIT_CAP = 256
         private_constant :CONSTANT_FOLD_ELEMENT_CAP, :CONSTANT_FOLD_BIT_CAP
 
-        # @return [Rigor::Type, nil]
         def try_dispatch(context)
           return nil unless REDUCE_METHODS.include?(context.method_name)
           return nil if context.block_type
@@ -84,9 +83,8 @@ module Rigor
         # Executes the reduction on real constant values, or returns nil to decline. The caller falls
         # through to the nominal fold on a nil return, so every guard here is precision-additive only.
         #
-        # @param seed [Rigor::Type, nil] the optional seed type; only a foldable `Constant` seed is
+        # @param seed — the optional seed type; only a foldable `Constant` seed is
         #   honoured, any other seed declines.
-        # @return [Rigor::Type::Constant, nil]
         def try_constant_reduce(receiver, operator, seed)
           return nil unless CONSTANT_FOLD_OPERATORS.include?(operator)
 
@@ -102,8 +100,6 @@ module Rigor
         # Extracts the receiver's elements as a Ruby Array of foldable constant values, or nil to decline.
         # Checks the size cap BEFORE enumerating so an unbounded / huge `Constant[Range]` (e.g.
         # `(1..1_000_000)`) never calls `to_a`.
-        #
-        # @return [Array, nil]
         def constant_members(receiver)
           case receiver
           when Type::Constant
@@ -140,7 +136,7 @@ module Rigor
           elements.map(&:value)
         end
 
-        # @return [Array(Object, Boolean)] `[seed_value, present?]`. A nil seed type yields `[nil, false]`
+        # @return `[seed_value, present?]`. A nil seed type yields `[nil, false]`
         #   (no-seed form). A foldable `Constant` seed yields `[value, true]`. Any other seed yields
         #   `[nil, false]` so the caller can decline.
         def constant_seed(seed)
@@ -153,8 +149,6 @@ module Rigor
         # Runs the actual reduction, guarded by the rescue harness and the magnitude cap. Empty-collection
         # semantics match Ruby: `[].reduce(s, :op) == s` (seed form) and `[].reduce(:op) == nil` (no-seed
         # form → declines so the nominal fold's no-nil contract stands; see `fold_result`).
-        #
-        # @return [Rigor::Type::Constant, nil]
         def execute_constant_reduce(members, operator, seed_value, seed_present)
           result =
             if seed_present

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

@@ -48,7 +48,7 @@ module Rigor
 
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

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

@@ -27,7 +27,7 @@ module Rigor
       module SetFolding
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

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

@@ -186,7 +186,7 @@ module Rigor
           itself: :shape_self
         }.freeze
 
-        # @return [Rigor::Type, nil] the precise element/value type, or `nil` to defer to the next
+        # @return the precise element/value type, or `nil` to defer to the next
         #   dispatcher tier.
         # Per-carrier dispatch table. Adding a new carrier here is a one-row change; the helper methods
         # stay private. Anonymous Type subclasses are not expected.

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

@@ -54,7 +54,7 @@ module Rigor
 
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

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

@@ -31,8 +31,7 @@ module Rigor
 
         module_function
 
-        # @param context [CallContext]
-        # @return [Rigor::Type, nil] `Nominal[C]` for `C.instance`, or nil to decline.
+        # @return `Nominal[C]` for `C.instance`, or nil to decline.
         def try_dispatch(context)
           return nil unless context.method_name == SELECTOR
           return nil unless context.args.empty?

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

@@ -45,7 +45,7 @@ module Rigor
         # Issue #595 / #525 — the shared materialisation test; see {StructMaterialization}.
         extend StructMaterialization
 
-        # @return [Rigor::Type, nil] the folded result, or nil to defer.
+        # @return the folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
 
@@ -344,10 +344,9 @@ module Rigor
         # local's true member state at every later read on the path. A non-fold-safe local is left untouched
         # (its reads do not fold, so the binding is never consulted for folding).
         #
-        # @param call_node    [Prism::CallNode]  the `local.member = v` call
-        # @param assigned_type [Rigor::Type, nil] the setter's assigned value type (the call's own result)
-        # @param scope        [Rigor::Scope, nil]
-        # @return             [Rigor::Scope]     the (possibly) rebound scope
+        # @param call_node — the `local.member = v` call
+        # @param assigned_type — the setter's assigned value type (the call's own result)
+        # @return the (possibly) rebound scope
         def apply_setter_writeback(call_node:, assigned_type:, scope:)
           return scope if scope.nil? || assigned_type.nil?
 

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

@@ -4,6 +4,8 @@ require "prism"
 
 require_relative "../../type"
 require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
+require_relative "../struct_fold_safety"
 
 module Rigor
   module Inference
@@ -25,6 +27,10 @@ module Rigor
       module StructMaterialization
         module_function
 
+        # Nodes one factory-body scan may visit before it gives up and refuses. A factory is a handful of
+        # nodes; the bound exists so a pathological body cannot turn a per-call-site gate into a walk.
+        FACTORY_BODY_SCAN_BUDGET = 200
+
         # Issue #595 / #525 — the ONE materialisation test. Both places that must answer "was this receiver
         # expression's struct newly built?" go through it: this module's direct member-read gate above, and
         # `ExpressionTyper`'s caller-side `:self`-grant arm. They had forked answers once (the grant arm was
@@ -32,20 +38,95 @@ module Rigor
         # composed `x.dup_self.with(indent: 9).shout` shape survived — a correctly whitelisted `.with` fold
         # firing off a receiver the other gate should never have called fresh.
         #
-        #
-        # @param node [Prism::Node, nil] the receiver EXPRESSION.
-        # @param receiver [Rigor::Type, nil] the carrier the expression produced.
-        # @param scope [Rigor::Scope, nil]
+        # @param node — the receiver EXPRESSION.
+        # @param receiver — the carrier the expression produced.
         def materialization_call?(node, receiver, scope)
           return false unless node.is_a?(Prism::CallNode)
 
           case node.name
           when :new, :[] then struct_class_expression?(node.receiver, scope)
           when :with then !hand_written_with?(receiver, scope)
+          else fresh_factory_call?(node, scope)
+          end
+        end
+
+        # Issue #599 — the FACTORY-METHOD idiom, the one shape #595's whitelist knowingly paid for as a
+        # missed error: `def build = Pair.new("hi", [1, 2])` then `build.items`. The whitelist could not see
+        # through `build`, so the chain declined and a typo on it went unreported.
+        #
+        # It is recovered by asking the callee, under two bounds that keep the answer cheap and fail-closed.
+        #
+        # 1. RESOLUTION is one table read on a shape whose target cannot be an arbitrary object: a
+        #    receiverless send resolved through the confidence-gated top-level def table, or `Const.name`
+        #    resolved through the singleton-side ancestor walk. An INSTANCE-side receiver is refused
+        #    outright — `x.dup_self` is the #595 bug shape, and what `x` holds at the call is exactly what
+        #    this gate has no way to know.
+        # 2. ACCEPTANCE is decided on the callee's RETURN POSITION, not on a self-alias scan of its body.
+        #    "Cannot return `self`" is not the property freshness needs: the factory's `self` is the module
+        #    or `main`, never the struct, while `def get = GLOBAL` over a mutated constant returns a
+        #    long-lived instance with no `self` anywhere in it. What the gate needs is that the returned
+        #    object was built BY THIS CALL, so the body's tail must itself be a materialisation
+        #    ({#fresh_materialization_tail?}) and no `return` may hand back anything else. That subsumes the
+        #    self-alias refusal — a body returning `self` has a `SelfNode` tail, not a `.new` — while
+        #    admitting the idiom the issue is about.
+        def fresh_factory_call?(node, scope)
+          return false if scope.nil?
+
+          body = factory_def_body(node, scope)
+          return false unless body.is_a?(Prism::StatementsNode)
+
+          fresh_materialization_tail?(body.body.last, scope) && !early_return?(body)
+        end
+
+        # The two CHEAPLY RESOLVABLE callee shapes, each a single table read against the frozen discovery
+        # index. `bindable_top_level_def_for` is the confidence-gated accessor — the only one the inference
+        # may bind through — so a call inside a block whose `self` is unmodelled declines here as it does
+        # everywhere else. Anything else, an instance-side receiver above all, resolves to nil.
+        def factory_def_body(node, scope)
+          def_node =
+            case node.receiver
+            when nil then scope.bindable_top_level_def_for(node.name)
+            when Prism::ConstantReadNode, Prism::ConstantPathNode
+              owner = Source::ConstantPath.qualified_name_or_nil(node.receiver)
+              owner && scope.singleton_def_through_ancestors(owner, node.name).first
+            end
+          def_node&.body
+        end
+
+        # A materialisation written in the CALLEE's body, judged syntactically. Deliberately narrower than
+        # {#struct_class_expression?}: that predicate's local-variable arm reads the binding off the scope it
+        # is handed, which is the CALLER's — a local of the same name in the callee body is a different
+        # binding entirely, so the arm is dropped rather than answered from the wrong scope.
+        def fresh_materialization_tail?(node, scope)
+          return false unless node.is_a?(Prism::CallNode)
+          return false unless %i[new []].include?(node.name)
+
+          case node.receiver
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            name = Source::ConstantPath.qualified_name_or_nil(node.receiver)
+            !name.nil? && !scope.struct_member_layout(name).nil?
+          when Prism::CallNode then inline_struct_factory?(node.receiver)
           else false
           end
         end
 
+        # An explicit `return` anywhere in the body hands back an expression the tail check never saw, so the
+        # body is refused rather than scanned arm by arm. Nested `def` / `class` / `module` bodies are a
+        # different method's returns; a block's `return` is this method's, so the walk descends into it. The
+        # visit budget is the fail-closed bound: a body too large to scan is not proven, and unproven is not
+        # fresh.
+        def early_return?(node, budget = [FACTORY_BODY_SCAN_BUDGET])
+          return true if node.is_a?(Prism::ReturnNode)
+          return false if Inference::StructFoldSafety.scope_boundary?(node)
+
+          budget[0] -= 1
+          return true if budget[0].negative?
+
+          found = false
+          node.rigor_each_child { |child| found ||= early_return?(child, budget) }
+          found
+        end
+
         # `.with` copies the receiver into a new instance — unless the struct wrote its own, which is free to
         # return `self` and would reopen the very hole above.
         #

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

@@ -28,7 +28,7 @@ module Rigor
 
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

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

@@ -68,8 +68,7 @@ module Rigor
 
         module_function
 
-        # @param context [CallContext]
-        # @return [Rigor::Type, nil] the receiver-independent return type, or nil to decline.
+        # @return the receiver-independent return type, or nil to decline.
         def try_dispatch(context)
           return nil unless context.receiver.is_a?(Type::Dynamic)
 

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

@@ -61,7 +61,7 @@ module Rigor
 
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

data/lib/rigor/inference/method_dispatcher.rb

@@ -24,6 +24,7 @@ require_relative "method_dispatcher/array_to_h_folding"
 require_relative "method_dispatcher/file_folding"
 require_relative "method_dispatcher/shellwords_folding"
 require_relative "method_dispatcher/math_folding"
+require_relative "method_dispatcher/random_folding"
 require_relative "method_dispatcher/time_folding"
 require_relative "method_dispatcher/regexp_folding"
 require_relative "method_dispatcher/cgi_folding"
@@ -54,19 +55,18 @@ module Rigor
     module MethodDispatcher # rubocop:disable Metrics/ModuleLength
       module_function
 
-      # @param receiver_type [Rigor::Type, nil] type of the receiver expression, or
+      # @param receiver_type — type of the receiver expression, or
       #   `nil` for an implicit-self call.
-      # @param method_name [Symbol]
-      # @param arg_types [Array<Rigor::Type>] positional argument types.
-      # @param block_type [Rigor::Type, nil] inferred return type of the
+      # @param arg_types — positional argument types.
+      # @param block_type — inferred return type of the
       #   accompanying `do ... end` / `{ ... }` block (Slice 6 phase C
       #   sub-phase 2). When non-nil, the dispatcher prefers an
       #   overload that declares a block, and binds the method's
       #   block-return type variable to `block_type` so a return type
       #   like `Array[U]` resolves to `Array[block_type]`.
-      # @param environment [Rigor::Environment, nil] required for
+      # @param environment — required for
       #   RBS-backed dispatch; when nil only constant folding can fire.
-      # @return [Rigor::Type, nil] inferred result type, or `nil` for "no rule".
+      # @return inferred result type, or `nil` for "no rule".
       def dispatch(receiver_type:, method_name:, arg_types:,
                    block_type: nil, environment: nil,
                    call_node: nil, scope: nil)
@@ -335,10 +335,14 @@ module Rigor
           [receiver_type.class_name, :instance]
         when Type::Singleton, Type::StructClass, Type::DataClass
           [receiver_type.class_name, :singleton]
-        else [nil, nil]
+        else NO_DISCOVERED_LOOKUP
         end
       end
 
+      # The shared "no discovered-method key" pair; callers destructure it (#775).
+      NO_DISCOVERED_LOOKUP = [nil, nil].freeze
+      private_constant :NO_DISCOVERED_LOOKUP
+
       # ADR-5 robustness — returns `Dynamic[Top]` when the receiver is an instance or singleton
       # of a type Rigor synthesized (a missing-namespace module or a referenced-type stub). The
       # stub has no methods, so the call would otherwise reach the user-class fallback and
@@ -759,6 +763,7 @@ module Rigor
         "File" => FileFolding,
         "Shellwords" => ShellwordsFolding,
         "Math" => MathFolding,
+        "Random" => RandomFolding,
         "Time" => TimeFolding,
         "Regexp" => RegexpFolding,
         "CGI" => CGIFolding,
@@ -1350,12 +1355,6 @@ module Rigor
       # method definition, or selected overload does not provide statically declared block
       # parameter types. Callers MUST treat the empty array as "no information"; the binder
       # falls back to `Dynamic[Top]` for every parameter slot in that case.
-      #
-      # @param receiver_type [Rigor::Type, nil]
-      # @param method_name [Symbol]
-      # @param arg_types [Array<Rigor::Type>]
-      # @param environment [Rigor::Environment, nil]
-      # @return [Array<Rigor::Type>]
       def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil)
         return [] if receiver_type.nil?
 

data/lib/rigor/inference/method_parameter_binder.rb

@@ -55,14 +55,13 @@ module Rigor
     end
 
     class MethodParameterBinder
-      # @param environment [Rigor::Environment]
-      # @param class_path [String, nil] the qualified name of the class the method is defined in
+      # @param class_path — the qualified name of the class the method is defined in
       #   (e.g., `"Foo::Bar"`), or `nil` for a top-level `def` outside any class. When `nil` (or
       #   when the class is unknown to RBS), every parameter falls back to `Dynamic[Top]`.
-      # @param singleton [Boolean] `true` when the def is a singleton method (either `def
+      # @param singleton — `true` when the def is a singleton method (either `def
       #   self.foo` or a `def foo` inside `class << self`); routes the lookup through
       #   `RbsLoader#singleton_method`.
-      # @param source_path [String, nil] the project-relative path of the file the method is
+      # @param source_path — the project-relative path of the file the method is
       #   defined in. Used to match ADR-28 path-scoped protocol contracts; `nil` (the default
       #   for synthetic / probe scopes) disables the contract tier.
       def initialize(environment:, class_path:, singleton:, source_path: nil)
@@ -72,8 +71,7 @@ module Rigor
         @source_path = source_path
       end
 
-      # @param def_node [Prism::DefNode]
-      # @return [Hash{Symbol => Rigor::Type}] ordered map from parameter name to bound type.
+      # @return ordered map from parameter name to bound type.
       #   Anonymous parameters (`*` and `**` without a name) are skipped.
       def bind(def_node)
         slots = collect_slots(def_node.parameters)

data/lib/rigor/inference/multi_target_binder.rb

@@ -50,9 +50,7 @@ module Rigor
     module MultiTargetBinder
       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}]
+      # @param rhs_type — type of the right-hand side
       def bind(target_node, rhs_type)
         bindings = {}
         visit(target_node, rhs_type, bindings)

data/lib/rigor/inference/mutation_rejoin.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "content_join"
+
+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
+        rejoined = keep_precise_parameters(pre_state, rejoined)
+        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