rigortype 0.4.6 → 0.4.7

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

@@ -20,8 +20,9 @@ module Rigor
       # The rule is exact rather than heuristic — the receiver must be a `Singleton[C]` whose `C` the project
       # pre-pass recorded as including `Singleton` — so a class that does not include the mixin is untouched,
       # and a project that defines its own `Singleton` module is the one case that would misfire. Guarded by
-      # {project_singleton_shadow?}: a project-declared `Singleton` class or module wins and the tier declines,
-      # because then the name means something else entirely.
+      # {own_singleton_include?}: when the included name resolves to a project-declared class or module (a
+      # top-level `Singleton`, or `M::Singleton` inside `module M`), the tier declines, because then the name
+      # means something else entirely.
       module SingletonMixinDispatch
         MIXIN_NAMES = Ractor.make_shareable(Set["Singleton", "::Singleton"])
         private_constant :MIXIN_NAMES
@@ -31,30 +32,62 @@ module Rigor
 
         module_function
 
-        # @return `Nominal[C]` for `C.instance`, or nil to decline.
+        # @return the instance type of `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?
-
           receiver = context.receiver
-          return nil unless receiver.is_a?(Type::Singleton)
-
-          scope = context.scope
-          return nil if scope.nil?
-          return nil unless includes_singleton_mixin?(scope, receiver.class_name)
-          return nil if project_singleton_shadow?(scope)
+          return nil unless answers?(context.scope, receiver, context.method_name, context.args.empty?)
 
           Type::Combinator.nominal_of(receiver.class_name)
         end
 
+        # Issue #2438 — the one predicate behind {try_dispatch} and `CheckRules#undefined_method_diagnostic`, so the
+        # typer and the `call.undefined-method` rule cannot disagree about `C.instance`: a call this tier types is
+        # never reported as undefined, whatever a project sidecar of `C` lists.
+        def answers?(scope, receiver, method_name, no_arguments)
+          return false unless method_name == SELECTOR && no_arguments
+          return false unless receiver.is_a?(Type::Singleton)
+          return false if scope.nil?
+
+          includes_singleton_mixin?(scope, receiver.class_name)
+        end
+
+        # True when `class_name`'s instance ancestry carries the stdlib `Singleton` as an `include` written in the
+        # class itself or in a project class up its superclass chain (Ruby's `Singleton.included` also installs an
+        # `inherited` hook, so `class D < C` answers `instance` with its own instance). Read off
+        # `Scope::ResolutionChain` (the `:constants` flavor, so an empty project `module Singleton` is a project
+        # entry), where the stdlib module is an external entry. Issue #2438 — what is not the mixin:
+        #
+        # - `prepend Singleton`, which runs `prepend_features` instead of the `included` hook and so defines no
+        #   `instance`; a prepended entry sits ahead of its owner on the chain;
+        # - an `include Singleton` in a MODULE the class includes: `Singleton.included` raises `TypeError` for a
+        #   module, so that code never runs;
+        # - a top-level project `Singleton`, which both `Singleton` and `::Singleton` name.
+        #
+        # A NESTED project `N::Singleton` the name resolved to is read as the stdlib mixin: the discovery tables
+        # drop the leading `::` of a mixin argument, so `include ::Singleton` and `include Singleton` inside
+        # `module N` record the same name, and the stdlib reading is the one that types the rooted spelling and
+        # never reports a correct call.
         def includes_singleton_mixin?(scope, class_name)
-          scope.includes_of(class_name).any? { |name| MIXIN_NAMES.include?(name.to_s) }
+          chain = Scope::ResolutionChain.for(scope, class_name.to_s.delete_prefix("::"), :instance, :constants)
+          chain.record(scope)
+          classes = chain.level_classes.compact
+          chain.entries.each_with_index.any? { |entry, index| singleton_include?(chain, classes, entry, index) }
+        end
+
+        def singleton_include?(chain, classes, entry, index)
+          if entry.external?
+            !entry.superclass_edge && MIXIN_NAMES.include?(entry.raw.to_s) && classes.include?(entry.owner) &&
+              index > chain.index_of(entry.owner)
+          else
+            entry.name.end_with?("::Singleton") && included_by_level_class?(chain, index)
+          end
         end
 
-        # True when the project declares its OWN `Singleton` class / module, in which case `include Singleton`
-        # names that one and the stdlib rule does not apply.
-        def project_singleton_shadow?(scope)
-          MIXIN_NAMES.any? { |name| scope.discovery.discovered_classes.key?(name.to_s.delete_prefix("::")) }
+        # The entry sits after its level's class, so it was included into that level rather than prepended.
+        def included_by_level_class?(chain, index)
+          level = chain.level_starts.rindex { |start| start <= index }
+          klass = level && chain.level_classes[level]
+          !klass.nil? && index > chain.index_of(klass)
         end
       end
     end

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

@@ -14,8 +14,8 @@ module Rigor
       #
       # A `Struct` instance is mutable (`s.x = v`, `s[:x] = v`, escape), so a member map bound to a
       # variable can be invalidated by a later write. A member read folds off a **fresh** instance (the
-      # transient receiver of a `.new(...).x` / `.with(...).x` chain, unmutatable between materialisation
-      # and the read — slices 1+2), off a **fold-safe stored local** the {Inference::StructFoldSafety} scan
+      # transient receiver of a `.new(...).x` chain, unmutatable between materialisation and the read —
+      # slices 1+2), off a **fold-safe stored local** the {Inference::StructFoldSafety} scan
       # proved is never mutated / aliased / escaped (slice 3), or off a **setter-mutated fold-safe local**
       # whose bindings {#apply_setter_writeback} keeps current (slice 4). Any other stored receiver degrades
       # to `Dynamic[top]` rather than fold a possibly-stale value.
@@ -255,8 +255,8 @@ module Rigor
         end
 
         # A member read is foldable when the receiver is either FRESH (the transient result of a
-        # `.new(...)`/`.with(...)` chain, which cannot have been mutated between materialisation and this
-        # read) or a FOLD-SAFE stored local (ADR-48 slice 3 — `StructFoldSafety` proved the binding is
+        # `.new(...)` chain, which cannot have been mutated between materialisation and this read) or a
+        # FOLD-SAFE stored local (ADR-48 slice 3 — `StructFoldSafety` proved the binding is
         # never mutated / aliased / escaped in its scope).
         def foldable_receiver?(context)
           fresh_receiver?(context) || fold_safe_local_receiver?(context) ||
@@ -308,7 +308,7 @@ module Rigor
         end
 
         # A fresh receiver is the result of a chained call that MATERIALISED the struct — `Point.new(1, 2).x`,
-        # `Point[1, 2].x`, `inst.with(x: 9).y`. Not merely a chained call: slices 1-2 read "chained" as
+        # `Point[1, 2].x`. Not merely a chained call: slices 1-2 read "chained" as
         # "cannot have been mutated between materialisation and the read", and a method that hands back its
         # own receiver falsifies that (issue #595):
         #

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

@@ -31,12 +31,10 @@ module Rigor
         # 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
-        # tightened for #591 while this one still trusted any chained call), so both consumers must share this
-        # one answer. A `.with` call is never a materialisation: the composed `x.dup_self.with(indent: 9)`
-        # shape once slipped through as one, and `Struct#with` no longer exists to fold (#1335).
+        # Issue #595 / #525 — the ONE materialisation test, shared by {StructFolding#fresh_receiver?} and
+        # `ExpressionTyper`'s `:self`-grant arm so the two gates cannot fork. A `.with` call is never a
+        # materialisation: the composed `x.dup_self.with(indent: 9)` shape once slipped through as one, and
+        # `Struct#with` no longer exists (#1335).
         #
         # @param node — the receiver EXPRESSION.
         # @param scope — the scope the factory and ancestor lookups resolve against.

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

@@ -55,7 +55,7 @@ module Rigor
 
         # A form long enough to suggest generated or accumulated data rather than a literal a reader wrote;
         # past it the folded `Constant[String]` stops being useful in a diagnostic and only costs memory.
-        # Mirrors the byte ceiling `ShapeDispatch`'s own `tuple_join` fold applies for the same reason.
+        # Counts pairs where `ShapeDispatch`'s `tuple_join` fold caps bytes, for the same reason.
         FORM_PAIR_LIMIT = 64
         private_constant :FORM_PAIR_LIMIT
 

data/lib/rigor/inference/method_dispatcher.rb

@@ -41,6 +41,7 @@ require_relative "method_dispatcher/universal_object_dispatch"
 require_relative "method_dispatcher/singleton_mixin_dispatch"
 require_relative "method_dispatcher/method_folding"
 require_relative "method_dispatcher/optional_count"
+require_relative "../run_scoped_slots"
 
 module Rigor
   module Inference
@@ -204,8 +205,8 @@ module Rigor
         # user-authored RBS overrides substrate synthesis) and ABOVE the dependency-source
         # inference tier so a plugin's declared emit table beats the generic gem-source fallback
         # for the same class. Slice 6a-TierB (origin_module dispatch) lands precise return types
-        # for Tier B emissions; Tier C emissions still return `Dynamic[T]` at this tier (slice 6b
-        # is the Tier C promotion via ADR-13's resolver chain).
+        # for Tier B emissions; Tier C emissions return their manifest `return_type` when the environment
+        # names that class (slice 6b), and `Dynamic[T]` otherwise.
         synthetic_result = try_synthetic_method(
           receiver_type, method_name, arg_types, block_type, environment
         )
@@ -915,8 +916,7 @@ module Rigor
         result || EMPTY_CONTRIBUTIONS
       end
 
-      # Runs the precision tiers (constant fold, shape dispatch, file-path fold, block fold) in
-      # order and returns the first non-nil answer. Each tier owns its own receiver/argument
+      # Runs the precision tiers in order and returns the first non-nil answer. Each tier owns its own receiver/argument
       # shape checks; a tier that does not recognise the receiver returns nil so the next tier
       # can try. The RBS tier sits below this chain and is invoked by the outer `dispatch`
       # method.
@@ -925,7 +925,7 @@ module Rigor
       # (`try_dispatch(CallContext) -> Type?`). Order is significant: ConstantFolding's
       # exact-value folds win first, the stdlib singleton folders sit in the middle (each
       # gates on a distinct `Singleton` receiver, so their relative order is immaterial), and
-      # BlockFolding runs last because its rules only apply to block-taking calls — the cheaper
+      # BlockFolding runs near the end because its rules only apply to block-taking calls — the cheaper
       # arity folds above it filter the common cases first. Adding a precise tier is a one-line
       # append here rather than another link in a hand-written `||` ladder.
       PRECISE_TIERS_HEAD = Ractor.make_shareable([
@@ -1031,6 +1031,7 @@ module Rigor
         fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
         return nil if fallback_receiver.nil?
         return nil if declared_by_external_ancestor?(receiver_type, environment, context)
+        return nil if project_singleton_definer?(receiver_type, context)
 
         # Preserve the ORIGINAL receiver type as the `self` substitution so `Kernel#dup: () ->
         # self` and other `self`-returning methods route through Object's RBS while still
@@ -1078,7 +1079,54 @@ module Rigor
                                                         record_dependencies: false).nil?
       end
 
-      EXTERNAL_ANCESTOR_MEMO_KEY = :__rigor_user_class_fallback_external_ancestor__
+      # Issue #2284 — a class object whose singleton chain holds a project definer of the name (its own `def
+      # self.name`, one a project superclass wrote, an `extend`ed module's `def name`) answers from that definer,
+      # not from `Module#name` / `Class#…` on the `Singleton[Object]` fallback: Ruby's singleton ancestry puts
+      # every project entry ahead of `Class`. The fallback declines so the typer's singleton-body inference
+      # answers the definer's return, or `Dynamic` where the slot is contested and the def may not be the one
+      # that runs.
+      #
+      # The chain walk files the class edge of every entry it passes, so it runs only for a name some project file
+      # defines at all ({BlockCallTiming.project_defines_anywhere?}, which files the `defines:<name>` edge either way,
+      # #1459). Without it every class-body `private` / `attr_reader` call on a project class would depend on its
+      # whole ancestry. The by-name answer is memoised per discovery index; the edge is filed on every call.
+      def project_singleton_definer?(receiver_type, context)
+        return false unless receiver_type.is_a?(Type::Singleton)
+
+        scope = context.scope
+        return false if scope.nil?
+        return false unless project_defines_name?(scope, context.method_name)
+
+        !scope.singleton_def_through_ancestors(receiver_type.class_name, context.method_name).last.nil?
+      end
+
+      def project_defines_name?(scope, method_name)
+        memo = defines_name_memo(scope)
+        if memo.key?(method_name)
+          Analysis::DependencyRecorder.read_missing(:defines, method_name) if Analysis::DependencyRecorder.active?
+          return memo[method_name]
+        end
+
+        memo[method_name] = BlockCallTiming.project_defines_anywhere?(method_name, scope)
+      end
+
+      DEFINES_NAME_MEMO_KEY = RunScopedSlots.register(:__rigor_user_class_fallback_defines_name__)
+      private_constant :DEFINES_NAME_MEMO_KEY
+
+      # One slot per discovery index and environment, as {#external_ancestor_memo} keeps its own: the answer reads
+      # only the frozen discovery tables and the environment's `pre_eval:` patches.
+      def defines_name_memo(scope)
+        discovery = scope.discovery
+        environment = scope.environment
+        slot = Thread.current[DEFINES_NAME_MEMO_KEY]
+        unless slot && slot[0].equal?(discovery) && slot[1].equal?(environment)
+          slot = [discovery, environment, {}]
+          Thread.current[DEFINES_NAME_MEMO_KEY] = slot
+        end
+        slot[2]
+      end
+
+      EXTERNAL_ANCESTOR_MEMO_KEY = RunScopedSlots.register(:__rigor_user_class_fallback_external_ancestor__)
       private_constant :EXTERNAL_ANCESTOR_MEMO_KEY
 
       # One slot per discovery index and environment, as `RbsDispatch#ancestor_memo_slot` keeps its own: the answer
@@ -1138,12 +1186,14 @@ module Rigor
       #
       # `RbsDispatch` already distributes over a `Union` (and erases a `Difference` to its base, #533),
       # but it does so INSIDE one tier, so a member that needs a LOWER tier — a user class with no RBS,
-      # a discovered `def`, an opt-in gem — makes the whole union decline. That is the corpus shape:
-      # rigor-actionpack types `params[:k]` as `ActionController::Parameters | nil`, the `Parameters` arm
-      # resolves only through the user-class fallback, and so `params[:k].present?` / `#==` / `#blank?` /
-      # `#to_s` read opaque on every Rails app. Measured by toggling this file alone: the named-pair
-      # census drains 137 sites on redmine and 56 on mastodon, and `rigor check` reports the same
-      # diagnostics on both arms across eight survey targets.
+      # a discovered `def`, an opt-in gem — makes the whole union decline. That was the corpus shape before
+      # #2430: rigor-actionpack typed `params[:k]` as the bare `ActionController::Parameters | nil` union, the
+      # `Parameters` arm resolved only through the user-class fallback, and so `params[:k].present?` / `#==`
+      # / `#blank?` / `#to_s` read opaque on every Rails app. Measured by toggling this file alone: the
+      # named-pair census drained 137 sites on redmine and 56 on mastodon, and `rigor check` reported the
+      # same diagnostics on both arms across eight survey targets. The plugin now answers a `Dynamic`
+      # carrier, which this projection does not reach, so those off-chain calls read `Dynamic[top]` until
+      # the carrier is projected here too (#2448).
       #
       # **Why the bottom and not next to `RbsDispatch`.** Sitting here, the tier can only ever replace a
       # `Dynamic[top]` the typer was about to produce — the same ADR-5 argument {UniversalObjectDispatch}
@@ -1346,8 +1396,8 @@ module Rigor
       # class is representable as the parent's singleton type — its singleton-method surface is
       # the parent's (plus whatever the block defines, which we do not statically track here),
       # so `Singleton[Parent]` lets downstream `klass.some_class_method` resolve. No parent →
-      # `singleton(Object)`. Anything else (dynamic parent, more than one positional, …) falls
-      # back to `Nominal[Class]` via the surrounding `meta_new` tail.
+      # `singleton(Object)` (or the block's anonymous class, #319 below). Anything else (dynamic parent, more
+      # than one positional, …) falls back to `Nominal[Class]` via the surrounding `meta_new` tail.
       # #319 — a `Class.new do ... end` with no parent is NOT `Object`: the block body is a class body, so the
       # class owns whatever that body defines. Answering `Singleton[Object]` handed the call site `Object`'s
       # zero-arity `new` and `Object`'s method surface, so an `initialize(bucket)` written right there produced

data/lib/rigor/inference/module_function_state.rb

@@ -76,6 +76,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 +353,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]

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`).

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`