rigortype 0.4.6 → 0.4.8

data/lib/rigor/inference/method_parameter_binder.rb

@@ -54,6 +54,114 @@ module Rigor
       end
     end
 
+    # Issue #2681 — which declared type, if any, one RBS overload hands a `def`'s parameter slot when the def's shape
+    # need not match the declaration's (an override bound from its ancestor, or a source `def` whose RBS was written
+    # for another shape). A slot takes a type only where the two shapes line up:
+    #
+    # - a leading positional (required or optional) takes the declared leading positional at the same ABSOLUTE
+    #   position, and a post positional the declared trailing one, provided both sides have as many post as
+    #   trailing positionals: Ruby fills the leading parameters left to right on both sides, so the argument a call
+    #   puts at a leading position reaches the slot at the same one;
+    # - `*rest` takes the declared rest only when the def has exactly the declared leading positionals;
+    # - a keyword takes the declared keyword of its name, and `**kw` the declared keyword rest only when the def
+    #   names every declared keyword.
+    #
+    # Any other overlap is {MISALIGNED}, and leaves the slot `Dynamic[Top]`. {NOT_PASSED} is an overload that passes
+    # the slot nothing (`def first(n)` under `Array#first`'s `()`), which the binder skips.
+    module SlotAlignment
+      module_function
+
+      MISALIGNED = :misaligned
+      NOT_PASSED = :not_passed
+
+      # `accepts_keywords` is false for a def with no keyword parameter and no `**`, `**nil` or `...`: Ruby passes a
+      # call's keywords to such a def as a Hash in one more positional argument.
+      Shape = Data.define(:requireds, :leading, :posts, :keywords, :accepts_keywords)
+
+      def shape_of(params_node)
+        return Shape.new(0, 0, 0, [].freeze, false) if params_node.nil?
+
+        requireds = params_node.requireds.size
+        keywords = params_node.keywords.map(&:name).freeze
+        accepts_keywords = !keywords.empty? || !params_node.keyword_rest.nil?
+        Shape.new(requireds, requireds + params_node.optionals.size, params_node.posts.size, keywords,
+                  accepts_keywords)
+      end
+
+      # The RBS type the overload `function` declares for `slot`, {MISALIGNED} or {NOT_PASSED}.
+      def declared(function, slot, shape)
+        return MISALIGNED if keyword_hash_reaches?(function, slot, shape)
+
+        case slot.kind
+        when :required_positional then leading(function, shape, slot.index)
+        when :optional_positional then leading(function, shape, shape.requireds + slot.index)
+        when :trailing_positional then trailing(function, shape, slot.index)
+        when :rest_positional then rest(function, shape)
+        when :required_keyword, :optional_keyword then keyword(function, slot.name)
+        when :rest_keyword then rest_keyword(function, shape)
+        else NOT_PASSED
+        end
+      end
+
+      # Whether the overload's keywords may reach `slot` as a positional Hash: the def accepts no keywords, so a
+      # call's keywords arrive as one more positional argument, which lands past the declared required leading
+      # positionals, in the `*rest`, or (shifting every post positional) in a post positional.
+      def keyword_hash_reaches?(function, slot, shape)
+        return false if shape.accepts_keywords
+        return false if function.required_keywords.empty? && function.optional_keywords.empty? &&
+                        function.rest_keywords.nil?
+
+        case slot.kind
+        when :required_positional then slot.index >= function.required_positionals.size
+        when :optional_positional then shape.requireds + slot.index >= function.required_positionals.size
+        when :rest_positional, :trailing_positional then true
+        else false
+        end
+      end
+
+      def leading(function, shape, position)
+        return MISALIGNED unless function.trailing_positionals.size == shape.posts
+
+        required = function.required_positionals
+        return required[position].type if position < required.size
+
+        optional = function.optional_positionals[position - required.size]
+        return optional.type if optional
+
+        function.rest_positionals ? MISALIGNED : NOT_PASSED
+      end
+
+      def trailing(function, shape, index)
+        return MISALIGNED unless function.trailing_positionals.size == shape.posts
+
+        function.trailing_positionals[index].type
+      end
+
+      def rest(function, shape)
+        return MISALIGNED unless function.trailing_positionals.size == shape.posts
+
+        declared_leading = function.required_positionals.size + function.optional_positionals.size
+        return MISALIGNED if shape.leading < declared_leading
+        return NOT_PASSED if function.rest_positionals.nil?
+
+        shape.leading == declared_leading ? function.rest_positionals.type : MISALIGNED
+      end
+
+      def keyword(function, name)
+        declared = function.required_keywords[name] || function.optional_keywords[name]
+        return declared.type if declared
+
+        function.rest_keywords ? MISALIGNED : NOT_PASSED
+      end
+
+      def rest_keyword(function, shape)
+        declared = function.required_keywords.keys + function.optional_keywords.keys
+        return MISALIGNED unless declared.all? { |name| shape.keywords.include?(name) }
+
+        function.rest_keywords ? function.rest_keywords.type : NOT_PASSED
+      end
+    end
+
     class MethodParameterBinder
       # @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
@@ -64,11 +172,15 @@ module Rigor
       # @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)
+      # @param scope — the scope the `def` is written in. When supplied, a `def` on a Ruby-source class with no RBS
+      #   of its own binds the parameters of the declaration it overrides on an ADR-43 allow-listed ancestor (#2681);
+      #   `nil` keeps that class's parameters `Dynamic[Top]`.
+      def initialize(environment:, class_path:, singleton:, source_path: nil, scope: nil)
         @environment = environment
         @class_path = class_path
         @singleton = singleton
         @source_path = source_path
+        @scope = scope
       end
 
       # @return ordered map from parameter name to bound type.
@@ -79,7 +191,9 @@ module Rigor
 
         rbs_method = lookup_rbs_method(def_node)
         if rbs_method
-          apply_rbs_overloads(types, slots, rbs_method.method_types) unless rbs_method.method_types.empty?
+          unless rbs_method.method_types.empty?
+            apply_rbs_overloads(types, slots, rbs_method.method_types, SlotAlignment.shape_of(def_node.parameters))
+          end
           # `rigor:v1:param: <name> <refinement>` annotations tighten the bound type for matching
           # slots. Applied after the RBS-overload pass so the override is the authoritative
           # answer regardless of what the RBS signature declared.
@@ -186,15 +300,17 @@ module Rigor
         # `def self.foo` always means a singleton method on the immediate enclosing class. `def
         # foo` inside `class << self` is also a singleton method (the StatementEvaluator threads
         # the `singleton:` flag through this case).
-        if def_node.receiver.is_a?(Prism::SelfNode) || @singleton
-          Rigor::Reflection.singleton_method_definition(@class_path, method_name, environment: @environment)
-        else
-          Rigor::Reflection.instance_method_definition(@class_path, method_name, environment: @environment)
-        end
+        # ADR-43 (#2681) — a source-only subclass of an allow-listed RBS-complete ancestor (`Rigor::Plugin::Base`)
+        # overriding one of its hooks binds the hook's declared parameters, as an empty RBS declaration of the
+        # subclass would through RBS's own inheritance.
+        kind = def_node.receiver.is_a?(Prism::SelfNode) || @singleton ? :singleton : :instance
+        MethodDispatcher::RbsDispatch.def_declaration(@environment, @class_path, kind, method_name, @scope)
       end
 
       # Bind each parameter slot to the union of the matching parameter types across every
-      # overload that *has* that slot. Overloads that omit the slot (e.g., `Array#first` has
+      # overload that *has* that slot, where the def's parameter shape lines up with the overload's
+      # ({SlotAlignment}); one overload that does not line up leaves the slot `Dynamic[Top]`.
+      # Overloads that pass the slot no argument (e.g., `Array#first` has
       # both `()` and `(int)` overloads — only the second matches a `def first(n)` redefinition)
       # are silently skipped, so the binder defaults to the most informative type the RBS
       # signature provides without having to know which overload the runtime will pick.
@@ -203,14 +319,14 @@ module Rigor
       # accepts any argument in every slot, so no slot can be narrowed below `Dynamic[Top]`: binding a typed
       # sibling overload's parameter type would read a value that overload legitimately passes as a
       # contradiction inside the body. Every slot keeps its default; the declared return type still applies.
-      def apply_rbs_overloads(types, slots, method_types)
+      def apply_rbs_overloads(types, slots, method_types, shape)
         return unless method_types.all? { |mt| mt.type.respond_to?(:required_positionals) }
 
         slots.each do |slot|
           next if slot.name.nil?
 
-          translated = collect_translated_types(method_types, slot)
-          next if translated.empty?
+          translated = collect_translated_types(method_types, slot, shape)
+          next if translated.nil? || translated.empty?
 
           types[slot.name] = build_slot_type(translated, slot.kind)
         end
@@ -272,10 +388,15 @@ module Rigor
         slots.find { |slot| POSITIONAL_KINDS.include?(slot.kind) && slot.index == index }
       end
 
-      def collect_translated_types(method_types, slot)
-        rbs_types = method_types.flat_map do |mt|
-          t = rbs_type_for_slot(mt.type, slot)
-          t ? [t] : []
+      # The translated types the overloads declare for `slot`, or nil when one of them does not line up with the
+      # def's parameter shape ({SlotAlignment}): that overload may hand the slot an argument of another type.
+      def collect_translated_types(method_types, slot, shape)
+        rbs_types = []
+        method_types.each do |mt|
+          declared = SlotAlignment.declared(mt.type, slot, shape)
+          return nil if declared.equal?(SlotAlignment::MISALIGNED)
+
+          rbs_types << declared unless declared.equal?(SlotAlignment::NOT_PASSED)
         end
         rbs_types.map { |t| translate_with_self(t) }.uniq
       end
@@ -285,47 +406,6 @@ module Rigor
         wrap_for_kind(bound, kind)
       end
 
-      # Dispatch table from slot kind to a small lambda that pulls the matching RBS parameter
-      # type out of an `RBS::Types::Function`. The hash keeps `rbs_type_for_slot` linear (one
-      # lookup, one call) so the cyclomatic-complexity budget does not balloon as future slices
-      # add more parameter kinds (e.g., `**Symbol kw` is a candidate for a stricter route in
-      # Slice 5+).
-      # Match keyword parameters by name across both required and optional keyword maps. RBS may
-      # declare a keyword as optional (`?by:`) while the Ruby `def` lists it as required (or
-      # vice versa); the binding is by-name regardless of which side defines it.
-      KEYWORD_PROVIDER = Ractor.make_shareable(lambda do |fn, slot|
-        fn.required_keywords[slot.name]&.type || fn.optional_keywords[slot.name]&.type
-      end)
-      private_constant :KEYWORD_PROVIDER
-
-      RBS_TYPE_PROVIDERS = Ractor.make_shareable({
-                                                   required_positional: Ractor.make_shareable(lambda { |fn, slot|
-                                                     fn.required_positionals[slot.index]&.type
-                                                   }),
-                                                   optional_positional: Ractor.make_shareable(lambda { |fn, slot|
-                                                     fn.optional_positionals[slot.index]&.type
-                                                   }),
-                                                   rest_positional: Ractor.make_shareable(lambda { |fn, _slot|
-                                                     fn.rest_positionals&.type
-                                                   }),
-                                                   trailing_positional: Ractor.make_shareable(lambda { |fn, slot|
-                                                     fn.trailing_positionals[slot.index]&.type
-                                                   }),
-                                                   required_keyword: KEYWORD_PROVIDER,
-                                                   optional_keyword: KEYWORD_PROVIDER,
-                                                   rest_keyword: Ractor.make_shareable(lambda { |fn, _slot|
-                                                     fn.rest_keywords&.type
-                                                   })
-                                                 })
-      private_constant :RBS_TYPE_PROVIDERS
-
-      def rbs_type_for_slot(function, slot)
-        provider = RBS_TYPE_PROVIDERS[slot.kind]
-        return nil unless provider
-
-        provider.call(function, slot)
-      end
-
       # The variable bound to a `*rest` parameter is the *Array* of rest-positional arguments,
       # not a single element. Likewise `**kw` is bound to a `Hash[Symbol, V]`. Wrap the
       # translated element/value type accordingly so `rest` reads as `Array[Integer]` rather

data/lib/rigor/inference/module_function_state/spellings.rb

@@ -41,8 +41,8 @@ module Rigor
           any = arguments.empty?
           arguments.each do |arg|
             if arg.is_a?(Prism::DefNode)
-              kind = ScopeIndexer.def_singleton?(arg, qualified_prefix, in_singleton_class) ? :singleton : :both
-              ranges << [arg.location.start_offset, arg.location.end_offset, arg.name, kind, owner]
+              ranges << [arg.location.start_offset, arg.location.end_offset, arg.name,
+                         *ModuleFunctionState.def_row_side(arg, qualified_prefix, in_singleton_class, owner)]
             elsif (name = Source::Literals.symbol_or_string(arg))
               ranges << [*call_span, name, :singleton, owner]
             else

data/lib/rigor/inference/module_function_state.rb

@@ -54,6 +54,17 @@ module Rigor
     module ModuleFunctionState
       module_function
 
+      # The `[kind, owner]` of a deferred-range row for a `def` passed to a `module_function` spelling: `:singleton`
+      # for a singleton def, `:both` for an instance one, and `[nil, nil]` for a def on another object's singleton
+      # (#3155), which claims no owner or side.
+      def def_row_side(def_node, qualified_prefix, in_singleton_class, owner)
+        case ScopeIndexer.def_side(def_node, qualified_prefix, in_singleton_class)
+        when :singleton then [:singleton, owner]
+        when :instance then [:both, owner]
+        else [nil, nil]
+        end
+      end
+
       # A receiverless `module_function` call, bare or named.
       def call?(node)
         node.name == :module_function && node.receiver.nil?
@@ -76,6 +87,17 @@ module Rigor
           (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode))
       end
 
+      # The `def` nodes a receiverless `public`, `private` or `protected` call takes as arguments (`private def x`,
+      # #2254). Ruby evaluates each one before the call, so it runs whenever the call's statement does. A named call
+      # with a symbol takes no def, and a call with a receiver is not read. A `module_function def` is not read here:
+      # its singleton copy is not modelled, so that gap stays as it was.
+      def visibility_call_defs(node)
+        return [] unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+        return [] unless %i[public private protected].include?(node.name)
+
+        node.arguments&.arguments&.grep(Prism::DefNode) || []
+      end
+
       # The mode after `stmt`, a direct statement of a body, for the readers that walk the statements: `mode`
       # is `true`, `false` or `:uncertain` before it. A {.visibility_reset?} the statement runs ends the mode,
       # and one it may not run (`:maybe_off`, below {.prescan_deferred}) makes an on mode uncertain. A
@@ -342,7 +364,6 @@ module Rigor
         true
       end
 
-      # The prescan's call arm.
       def prescan_call(node, qualified_prefix, in_singleton_class, offsets, ranges)
         if bare?(node)
           offsets << [node.location.start_offset, :on]
@@ -350,8 +371,8 @@ module Rigor
           owner = qualified_prefix.empty? ? nil : qualified_prefix.join("::")
           node.arguments&.arguments&.each do |arg|
             if arg.is_a?(Prism::DefNode)
-              kind = ScopeIndexer.def_singleton?(arg, qualified_prefix, in_singleton_class) ? :singleton : :both
-              ranges << [arg.location.start_offset, arg.location.end_offset, arg.name, kind, owner]
+              ranges << [arg.location.start_offset, arg.location.end_offset, arg.name,
+                         *ModuleFunctionState.def_row_side(arg, qualified_prefix, in_singleton_class, owner)]
             elsif (name = symbol_argument_name(arg))
               ranges << [node.location.start_offset, node.location.end_offset, name, :singleton, owner]
             else

data/lib/rigor/inference/multi_target_binder.rb

@@ -12,7 +12,7 @@ module Rigor
     #
     # `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 four surfaces:
+    # binder is shared between five surfaces:
     #
     # 1. `Rigor::Inference::StatementEvaluator#eval_multi_write` for the statement-level `a, b =
     #    rhs` form (`Prism::MultiWriteNode`).
@@ -302,7 +302,7 @@ module Rigor
         # 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 }
+          return [untyped, false] if types.any? { |type| Type::Combinator.untyped?(type) }
 
           firm = types.reject { |type| nil_literal?(type) }
           return [Type::Combinator.union(*types), false] if !soften_slots || firm.empty? || firm.size == types.size

data/lib/rigor/inference/mutation_rejoin.rb

@@ -31,7 +31,12 @@ module Rigor
       # `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)
+      def widen_nominal(nominal, method_name, values: :widen, arg_types: MutationWidening::NO_ARG_TYPES,
+                        synthesised: false)
+        if synthesised && (synthesised_carrier?(nominal) || partially_gradual_hash?(nominal))
+          return widen_synthesised(nominal, method_name, values:, arg_types:)
+        end
+        return widen_precise_array(nominal, method_name, values:, arg_types:) if precise_array?(nominal)
         return nil unless regrowable_carrier?(nominal)
 
         pre_state = values == :widen ? value_pin_widened_args(nominal) : nominal
@@ -115,19 +120,250 @@ module Rigor
       # 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.
+      # saying the collection may hold anything.
+      #
+      # Issue #2555 L3 — the provenance this boundary turns on travels beside the binding, not with the value: a
+      # local whose object the engine built carries the `:synthesised` construction fact ({Scope#construction_fact?}),
+      # and {#widen_synthesised} answers for it before this predicate is asked. A field on `Type::Nominal` was the
+      # other route; `Combinator.union`'s structural dedupe would keep whichever tagged twin it met first.
       def regrowable_carrier?(nominal)
         return false unless %w[Array Hash].include?(nominal.class_name)
 
         nominal.type_args.any? { |arg| gradual_parameter?(arg) }
       end
 
+      # Issue #2555 L3 — a PRECISE `Array` / `Hash` nominal (no parameter carries a `Dynamic` arm), the carrier
+      # {#widen_synthesised} re-grows when its binding carries the `:synthesised` fact. A carrier that already carries
+      # a gradual arm keeps the ordinary re-join, whose floor it holds already.
+      def synthesised_carrier?(nominal)
+        %w[Array Hash].include?(nominal.class_name) && !nominal.type_args.empty? &&
+          nominal.type_args.none? { |arg| gradual_parameter?(arg) }
+      end
+
+      # Issue #2555 L3 — a `Hash` with one gradual parameter and one precise one: `Hash.new(0)` is
+      # `Hash[Dynamic[top], Integer]`. On a synthesised binding the precise side is this engine's own fold of the
+      # default, not a declaration, so {#keep_precise_parameters} must not restore it over a store:
+      # `h = Hash.new(0); h[:y] = "s"` reads `Hash[Dynamic[top] | Symbol, Integer | String]`, not
+      # `Hash[Dynamic[top] | Symbol, Integer]` (which made `h[:y].upcase` an `undefined method` on Integer). The
+      # counter idiom keeps its `Integer`: `h[:x] += 1` stores an `Integer`.
+      def partially_gradual_hash?(nominal)
+        nominal.class_name == "Hash" && nominal.type_args.size == 2 &&
+          nominal.type_args.any? { |arg| gradual_parameter?(arg) } &&
+          nominal.type_args.any? { |arg| !gradual_parameter?(arg) }
+      end
+
+      # Issue #2555 L3 — the re-join for a precise carrier the engine built itself: a collection literal closed by a
+      # value-preserving mutator (`a = [1, 2]; a.sort!` is `Array[1 | 2]`, `g = { a: 1 }; g.delete(:b)` is
+      # `Hash[Symbol, 1]`), a constructor fold (`Array.new(n, 0)` is `Array[Integer]`), or a literal built as a
+      # nominal outright (`{ ENV["A"].to_s => 1 }`). Its element types are this engine's inference, not a claim a
+      # declaration made, so the #561 boundary ({#regrowable_carrier?}, {#precise_admitted}) does not apply:
+      #
+      # - an added member joins as itself (value pin and literal shape dropped, {MutationWidening.value_pin_widened}),
+      #   with no seed-admissibility gate and no `Dynamic[top]` floor — `Array.new(n, 0) << "s"` reads
+      #   `Array[Integer | String]`;
+      # - a rewriter takes {RewriteMutation.arm}'s gradual position, as a gradual carrier does —
+      #   `g.transform_values!(&:to_s)` reads `Hash[Symbol, Dynamic[top]]`;
+      # - an adder whose arguments yield no evidence is one unknown store and joins `Dynamic[top]`; one called with no
+      #   argument types at all (the block-capture seam, whose content join adds the stores afterwards) changes
+      #   nothing.
+      #
+      # The floor the ordinary re-join adds exists because a carrier it closed could not re-grow; this one stays
+      # re-growable while the binding keeps the fact, so every later store made THROUGH THE BINDING is seen. A store
+      # through another holder is not, which is why a local that may escape anywhere in its body never carries the
+      # fact ({ConstructionEscape}). Nor is a remover taking a store out again, which is why a remover on a carrier a
+      # store has grown restores the floor ({MutationWidening.floor_grown_carrier}).
+      def widen_synthesised(nominal, method_name, values:, arg_types:)
+        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)
+
+            synthesised_array_join(RewriteMutation.arm(pre_state, method_name), method_name, arg_types)
+          when "Hash"
+            return nil unless MutationWidening::HASH_MUTATORS.include?(method_name)
+
+            synthesised_hash_join(RewriteMutation.arm(pre_state, method_name), method_name, arg_types)
+          end
+        rejoined == nominal ? nil : rejoined
+      end
+
+      # Issue #2555 — the removers and filters of an Array, a Hash or a Set: each can take a stored member out again,
+      # which nothing narrows the carrier back from.
+      SYNTHESISED_REMOVERS = %i[
+        pop shift slice! delete delete? delete_at delete_if reject! select! filter! keep_if compact! clear subtract
+      ].to_set.freeze
+
+      # The adders whose store marks a synthesised binding `:grown`.
+      def content_adder?(method_name)
+        ContentJoin::CONTENT_ADDERS.include?(method_name) || SetMutation::CONTENT_ADDERS.include?(method_name)
+      end
+
+      # Whether a store turned `current` into `widened` by changing an Array / Hash / Set parameter that carried no
+      # `Dynamic` arm before it: a member joined where no floor covered it, which a later remover could leave stale.
+      # A store the parameter already held, or one that joined beside an earlier floor (`Hash.new(0)`'s key side),
+      # grows nothing.
+      def grew_unfloored?(current, widened)
+        return false if widened.nil?
+
+        before = ContentJoin.union_members(current)
+        ContentJoin.union_members(widened).any? do |member|
+          next false unless member.is_a?(Type::Nominal) && %w[Array Hash Set].include?(member.class_name)
+
+          prior = before.find { |b| same_carrier?(b, member) }
+          member.type_args.each_with_index.any? do |arg, i|
+            prior.nil? || (!gradual_parameter?(prior.type_args[i]) && prior.type_args[i] != arg)
+          end
+        end
+      end
+
+      def same_carrier?(type, nominal)
+        type.is_a?(Type::Nominal) && type.class_name == nominal.class_name &&
+          type.type_args.size == nominal.type_args.size
+      end
+
+      # Whether `method_name` on the synthesised local `name` takes the floor: a remover on a carrier a store grew.
+      def floors_grown_carrier?(scope, name, method_name)
+        SYNTHESISED_REMOVERS.include?(method_name) && scope.construction_fact?(name, :grown)
+      end
+
+      # `type` with every Array / Hash / Set parameter joined with `Dynamic[top]`, member-wise through a union: the
+      # reading the carrier would have had without the fact. With `drop_nil` (a remover that can take a `nil` out,
+      # {MutationWidening.removes_nil?}) the parameter's `nil` member goes too: on the path without the fact a stored
+      # `nil` the seed did not accept joined as the floor alone ({#precise_admitted}), and a `nil` kept beside the floor
+      # would still draw `call.possible-nil-receiver` after `parts << nil; parts.compact!`. Any other remover keeps the
+      # `nil`, which it may leave behind (`s << nil; s.delete(1)`).
+      def floor_parameters(type, drop_nil: false)
+        case type
+        when Type::Union then Type::Combinator.union(*type.members.map { |member| floor_parameters(member, drop_nil:) })
+        when Type::Nominal
+          return type unless %w[Array Hash Set].include?(type.class_name) && !type.type_args.empty?
+
+          Type::Combinator.nominal_of(type.class_name,
+                                      type_args: type.type_args.map { |arg| floored_parameter(arg, drop_nil) })
+        else type
+        end
+      end
+
+      def hash_carrier?(type)
+        ContentJoin.union_members(type).any? { |member| member.is_a?(Type::Nominal) && member.class_name == "Hash" }
+      end
+
+      def floored_parameter(arg, drop_nil)
+        kept = ContentJoin.union_members(arg)
+        kept = kept.reject { |member| member.is_a?(Type::Constant) && member.value.nil? } if drop_nil
+        Type::Combinator.union(*kept, Type::Combinator.untyped)
+      end
+
+      def synthesised_array_join(carrier, method_name, arg_types)
+        return carrier unless ContentJoin::ARRAY_CONTENT_ADDERS.include?(method_name) && !arg_types.empty?
+
+        added = MutationWidening.value_pin_widened(ContentJoin.array_added_elements(method_name, arg_types))
+        ContentJoin.join_array_content(carrier, added.empty? ? [Type::Combinator.untyped] : added)
+      end
+
+      def synthesised_hash_join(carrier, method_name, arg_types)
+        return carrier unless ContentJoin::HASH_CONTENT_ADDERS.include?(method_name) && !arg_types.empty?
+
+        # A `nil` key marks a splat, an unknown key ({MutationWidening.join_added_pairs}).
+        key, value = MutationWidening.value_pin_widened([arg_types.first || Type::Combinator.untyped, arg_types.last])
+        value ||= Type::Combinator.untyped
+        ContentJoin.join_hash_content(carrier, [[key, value]])
+      end
+
       def gradual_parameter?(type)
         ContentJoin.union_members(type).any?(Type::Dynamic)
       end
 
+      # A typed `Array[E]` whose `E` has no `Dynamic` arm — the carrier {#regrowable_carrier?} refuses.
+      def precise_array?(nominal)
+        nominal.class_name == "Array" && nominal.type_args.size == 1 && !gradual_parameter?(nominal.type_args.first)
+      end
+
+      # Issue #2361 — a PRECISE `Array[E]` re-grows under a store, on the literal arms' terms: `a = ARGV.dup;
+      # a.clear; a << 1; a.each { |v| v.fdiv(2) }` read `Array[String]` and reported `undefined method 'fdiv' for
+      # String` on code that prints `[0.5]`.
+      #
+      # Only a content adder ({ContentJoin::ARRAY_CONTENT_ADDERS}) re-grows it, and the join keeps the seed: `clear`
+      # empties the array but leaves `E` standing, a superset of what it holds. A remover leaves the carrier as it
+      # found it. An element rewriter (`map!`, `collect!`, `flatten!`) replaces `E` (issue #2427): with the element
+      # the non-bang counterpart answers when the call site could type it ({RewriteMutation.typed}, answered before
+      # this method), and otherwise with {RewriteMutation.arm}'s gradual element — `a.map!.with_index { … }` holds
+      # whatever the block returns, and keeping the stale `E` reported a missing method on correct code.
+      #
+      # Each added member the element accepts joins as itself; any other takes the `Dynamic[top]` floor
+      # ({#precise_admitted}), and the floor joins every re-grow as it does on the literal arms. `a << 1` therefore
+      # reads `Array[Dynamic[top] | String]` and `s = ints.map { "x" }; s << "y"` reads `Array["x" | Dynamic[top]]`.
+      # Nothing narrows a carrier back when a remover or rewriter takes the store out again (`a << 1; a.pop`,
+      # `a << nil; a.compact!`, `a.map!(&:to_s)`), so a joined `Integer` or `nil` made `t.take(a)` against a declared
+      # `Array[String]` report `call.argument-type-mismatch`, and a parameter returned as its declared
+      # `-> Array[String]` report `def.return-type-mismatch`, on correct Ruby. A union carrying the floor neither folds
+      # nor dispatches loudly, so the read stays silent. Once floored, the carrier is gradual and later stores re-join
+      # through {#widen_nominal}'s ordinary arm.
+      #
+      # A store the element already accepts changes nothing ({#already_held?}). An adder with no argument types at
+      # all is left alone, as {MutationWidening.join_added_elements} leaves it: the block-capture seams pass none,
+      # and their own content join adds the stores.
+      def widen_precise_array(nominal, method_name, values:, arg_types:)
+        return RewriteMutation.arm(nominal, method_name) if RewriteMutation::TYPED_COUNTERPARTS.key?(method_name)
+        return nil unless ContentJoin::ARRAY_CONTENT_ADDERS.include?(method_name) && !arg_types.empty?
+
+        stored = ContentJoin.array_added_elements(method_name, arg_types)
+        return nil if already_held?(nominal.type_args.first, stored)
+
+        added = MutationWidening.value_pin_widened(stored)
+        admitted = precise_admitted(nominal.type_args.first, added)
+        pre_state = values == :widen ? value_pin_widened_args(nominal) : nominal
+        rejoined = ContentJoin.join_array_content(pre_state, MutationWidening.gradual_floor(admitted))
+        rejoined == nominal ? nil : rejoined
+      end
+
+      # The seed-admissibility gate for a precise element: an added member joins as itself only when `element`
+      # already accepts it, and takes the `Dynamic[top]` floor otherwise. A precise element therefore never gains a
+      # member it rejects, which is what a declared boundary checks: nothing narrows the carrier back when a remover
+      # or rewriter takes the store out again, and a joined foreign arm stays rejected beside the floor — `Integer`
+      # under a declared `Array[String]`, `String` under `-> Array["x"]`, `Array[Integer]` under
+      # `Array[Array[String]]` each reported on correct Ruby. A class set ({ContentJoin.admissible_evidence}) is too
+      # coarse for that: it admits `Array[Integer]` beside `[String]` and `"y"` beside `"x"`.
+      def precise_admitted(element, added)
+        added.flat_map do |type|
+          ContentJoin.union_members(type).map do |member|
+            Acceptance.accepts(element, member).yes? ? member : Type::Combinator.untyped
+          end
+        end
+      end
+
+      # True when the precise element `element` already covers every type `stored` puts in, so the store changes
+      # nothing: `s = ints.map { "x" }; s << "x"` keeps `Array["x"]` and its `s.last == "x"` fold, which is correct,
+      # and a `[Integer, Integer]` pushed onto an `Array[[0 | Integer, Integer]]` keeps the Tuple element. Joining
+      # the value-pin-widened, shape-erased store instead would only lose precision.
+      #
+      # A stored type carrying `Dynamic` anywhere is never covered, though `Acceptance` passes it gradually: keeping
+      # the element would claim the unknown part is what the element says (`retry_binding_accepted?`'s rule).
+      def already_held?(element, stored)
+        return false if stored.empty?
+
+        held = ContentJoin.union_members(element)
+        stored.all? do |type|
+          next false if type.nil? || carries_dynamic?(type)
+
+          ContentJoin.union_members(type).all? { |member| held.include?(member) } ||
+            Acceptance.accepts(element, type).yes?
+        end
+      end
+
+      def carries_dynamic?(type)
+        case type
+        when Type::Dynamic then true
+        when Type::Union, Type::Intersection then type.members.any? { |member| carries_dynamic?(member) }
+        when Type::Nominal then type.type_args.any? { |arg| carries_dynamic?(arg) }
+        when Type::Tuple then type.elements.any? { |element| carries_dynamic?(element) }
+        when Type::HashShape then type.pairs.each_value.any? { |value| carries_dynamic?(value) }
+        when Type::Difference, Type::Refined then carries_dynamic?(type.base)
+        else false
+        end
+      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`