rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/acceptance.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "../type"
+require_relative "range_constant"
+require_relative "content_join"
 
 module Rigor
   module Inference
@@ -27,10 +29,7 @@ module Rigor
     module Acceptance
       module_function
 
-      # @param self_type [Rigor::Type]
-      # @param other_type [Rigor::Type]
-      # @param mode [Symbol] `:gradual` (default) or `:strict`.
-      # @return [Rigor::Type::AcceptsResult]
+      # @param mode — `:gradual` (default) or `:strict`.
       def accepts(self_type, other_type, mode: :gradual)
         raise ArgumentError, "Acceptance mode #{mode.inspect} is not implemented yet" unless mode == :gradual
 
@@ -63,6 +62,7 @@ module Rigor
         Type::Nominal => :accepts_nominal,
         Type::Constant => :accepts_constant,
         Type::IntegerRange => :accepts_integer_range,
+        Type::FloatRange => :accepts_float_range,
         Type::Difference => :accepts_difference,
         Type::Refined => :accepts_refined,
         Type::Intersection => :accepts_intersection,
@@ -75,10 +75,64 @@ module Rigor
       }.freeze
       private_constant :TYPE_HANDLERS
 
+      UNREAD_HASH_REFUSED_KEY = :__rigor_acceptance_unread_hash_refused__
+      private_constant :UNREAD_HASH_REFUSED_KEY
+
+      # Whether a `maybe` for `param` against `arg` rests on a record that could not read a hash's entries: a
+      # `Hash` with a gradual arm ({#gradual_hash?}) or an open `HashShape`. The record cannot prove the key set
+      # of either, and its `maybe` climbs through whatever holds the record. `OverloadSelector`'s strict pass
+      # reads that `maybe` as no evidence for the overload, so this re-asks with each such record answering
+      # `no` and reports whether the pair then fails. A `maybe` from anywhere else (a subclass only the Ruby
+      # source declares, a splat under a parameter that is no record) survives the re-ask and still counts.
+      def maybe_rests_on_unread_hash?(param, arg)
+        return false unless contains_type?(param) { |type| type.is_a?(Type::HashShape) }
+        return false unless contains_type?(arg) { |type| unread_hash?(type) }
+
+        refusing_unread_hashes { accepts(param, arg, mode: :gradual).no? }
+      end
+
       # rubocop:disable-next Metrics/ClassLength
       class << self
         private
 
+        # The flag lives on the thread, not on a parameter, because the record may sit any number of `accepts`
+        # calls below the one asked (a tuple element, a `Hash` value, a union member), and those calls go
+        # through each carrier's `Type#accepts`. It is set only for the duration of the block.
+        def refusing_unread_hashes
+          previous = Thread.current[UNREAD_HASH_REFUSED_KEY]
+          Thread.current[UNREAD_HASH_REFUSED_KEY] = true
+          yield
+        ensure
+          Thread.current[UNREAD_HASH_REFUSED_KEY] = previous
+        end
+
+        # The `maybe` a record answers for a hash whose entries it cannot read, or `no` inside
+        # {#refusing_unread_hashes}.
+        def unread_hash_maybe(mode, reason)
+          return hash_shape_no(mode, "#{reason} (refused as evidence)") if Thread.current[UNREAD_HASH_REFUSED_KEY]
+
+          Type::AcceptsResult.maybe(mode: mode, reasons: reason)
+        end
+
+        def unread_hash?(type)
+          gradual_hash?(type) || (type.is_a?(Type::HashShape) && type.open?)
+        end
+
+        def contains_type?(type, &)
+          return true if yield(type)
+
+          components =
+            case type
+            when Type::Union then type.members
+            when Type::Nominal then type.type_args
+            when Type::Tuple then type.elements
+            when Type::HashShape then type.pairs.values
+            when Type::Difference then [type.base]
+            else return false
+            end
+          components.any? { |component| contains_type?(component, &) }
+        end
+
         def accepts_one(self_type, other_type, mode)
           handler = TYPE_HANDLERS[self_type.class]
           return send(handler, self_type, other_type, mode) if handler
@@ -201,7 +255,8 @@ module Rigor
         #   {#accepts_nominal_args});
         # - Constant[v] when v.is_a?(klass(C)). The type_args of self are ignored here because a Constant
         #   carries a concrete value, not a generic instantiation, and the analyzer has no way to refute the
-        #   args from a literal alone.
+        #   args from a literal alone. A Range value is the one exception — see
+        #   {#accepts_range_constant_type_arg}.
         # - Tuple[*] when self is the Array (or a supertype) family. The Tuple is projected to
         #   `Nominal[Array, [union(elements)]]` so the existing generic-arg machinery handles it.
         # - HashShape{*} when self is the Hash (or a supertype) family, projected to
@@ -215,6 +270,7 @@ module Rigor
           when Type::Singleton then accepts_nominal_from_singleton(self_type, other_type, mode)
           when Type::StructClass, Type::DataClass then accepts_nominal_from_class_factory(self_type, other_type, mode)
           when Type::IntegerRange then accepts_nominal_from_integer_range(self_type, other_type, mode)
+          when Type::FloatRange then accepts_nominal_from_float_range(self_type, other_type, mode)
           else accepts_nominal_from_shape(self_type, other_type, mode)
           end
         end
@@ -311,6 +367,32 @@ module Rigor
           end
         end
 
+        # ADR-109 WD4 — the Float twin of the IntegerRange rule: `Nominal[Float]` and everything Float
+        # is-a accept any `FloatRange`; nothing else does.
+        FLOAT_NOMINAL_ANCESTORS = %w[Float Numeric Comparable Object BasicObject].freeze
+        private_constant :FLOAT_NOMINAL_ANCESTORS
+
+        def accepts_nominal_from_float_range(self_type, _other_type, mode)
+          unless self_type.type_args.empty?
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Nominal[#{self_type.class_name}] with type args rejects FloatRange"
+            )
+          end
+
+          if FLOAT_NOMINAL_ANCESTORS.include?(self_type.class_name)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "FloatRange is-a #{self_type.class_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Nominal[#{self_type.class_name}] rejects FloatRange"
+            )
+          end
+        end
+
         # v0.0.2 — meta-type rule. A `Singleton[T]` is the class object for `T`, so it is an instance of
         # `Class` (when `T` is a class) and always an instance of `Module`. Without this rule a method whose
         # parameter is typed `Class | Module` would reject every `is_a?(SomeClass)` call and similar
@@ -492,7 +574,7 @@ module Rigor
 
         def accepts_nominal_from_constant(self_type, constant, mode)
           ruby_class = resolve_class(self_type.class_name)
-          return constant_is_a_result(ruby_class, constant, self_type, mode) if ruby_class
+          return accepts_loaded_class_from_constant(ruby_class, constant, self_type, mode) if ruby_class
 
           # The host process may not have required the constant's declared self_type (e.g. `BigDecimal`
           # since Ruby 3.4 is no longer a default gem). Fall back to inspecting the value's own class
@@ -527,6 +609,13 @@ module Rigor
           end
         end
 
+        def accepts_loaded_class_from_constant(ruby_class, constant, self_type, mode)
+          result = constant_is_a_result(ruby_class, constant, self_type, mode)
+          return result unless result.yes?
+
+          accepts_range_constant_type_arg(self_type, constant, mode) || result
+        end
+
         def constant_is_a_result(ruby_class, constant, self_type, mode)
           if constant.value.is_a?(ruby_class)
             Type::AcceptsResult.yes(mode: mode, reasons: "Constant value is_a?(#{self_type.class_name})")
@@ -538,10 +627,53 @@ module Rigor
           end
         end
 
+        # Issue #833 — the single exception to "the type_args of self are ignored for a Constant".
+        #
+        # A `Constant<Range>` is the one literal that does pin a generic instantiation: the engine
+        # builds it only when both endpoints are static, so `Range[T]` CAN be refuted from the literal.
+        # Without this, `Nominal[Range, [Integer]]` accepted `0.0...1.0` and `OverloadSelector` pass 1
+        # pinned whichever `Range[…]` arm came first in declaration order — for `Kernel#rand` that is
+        # `(::Range[Integer]) -> Integer?`, ahead of every Float arm.
+        #
+        # Returns nil — "no opinion, keep the class-level answer" — outside the envelope: a raw `Range`
+        # or any other arity of type_args, and a range the shared reader cannot read endpoints from.
+        # A missing endpoint contributes nothing, because a beginless or endless literal inhabits
+        # `Range[T]` for every T (`Range[Integer?]` is the common core spelling of the slicing param).
+        #
+        # Known coarse spot, deliberately not special-cased: a mixed-endpoint literal (`1.0..2`) is
+        # rejected by `Range[Integer]` and by `Range[Float]` alike, so overload selection falls through
+        # to its gradual pass and then to the first-overload fallback exactly as it did before.
+        def accepts_range_constant_type_arg(self_type, constant, mode)
+          return nil unless self_type.type_args.size == 1
+
+          endpoints = RangeConstant.literal_endpoints(constant)
+          return nil if endpoints.nil?
+
+          element = self_type.type_args.first
+          combine_range_endpoint_results(
+            endpoints.map { |endpoint| accepts(element, Type::Combinator.constant_of(endpoint), mode: mode) },
+            element,
+            mode
+          )
+        end
+
+        def combine_range_endpoint_results(per_endpoint, element, mode)
+          if per_endpoint.any?(&:no?)
+            Type::AcceptsResult.no(mode: mode, reasons: "a Range endpoint is rejected by #{element.describe}")
+          elsif per_endpoint.any?(&:maybe?)
+            Type::AcceptsResult.maybe(
+              mode: mode,
+              reasons: "a Range endpoint could not be proven accepted by #{element.describe}"
+            )
+          else
+            Type::AcceptsResult.yes(mode: mode, reasons: "every Range endpoint accepted by #{element.describe}")
+          end
+        end
+
         # IntegerRange[a..b] accepts:
         # - Constant[n] where n is an Integer covered by [a..b];
         # - IntegerRange[c..d] where [c..d] ⊆ [a..b];
-        # - Nominal[Integer] only when self is the universal range (`int<min, max>`), since otherwise an
+        # - Nominal[Integer] only when self is the universal range (`Integer[min..max]`), since otherwise an
         #   arbitrary Integer could fall outside the bound.
         # Anything else is rejected.
         def accepts_integer_range(self_type, other_type, mode)
@@ -616,13 +748,77 @@ module Rigor
           end
         end
 
+        # ADR-109 WD4 — `FloatRange` accepts:
+        # - Constant[f] where f is a Float the range covers (never NaN: `cover?` compares);
+        # - FloatRange[c..d] whose canonical closed bounds sit inside self's.
+        # `Nominal[Float]` is never accepted, not even by the universal range: an arbitrary Float may be
+        # NaN, and the universal range is exactly "every Float except NaN".
+        def accepts_float_range(self_type, other_type, mode)
+          case other_type
+          when Type::Constant
+            accepts_float_range_from_constant(self_type, other_type, mode)
+          when Type::FloatRange
+            accepts_float_range_from_float_range(self_type, other_type, mode)
+          when Type::Nominal
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{self_type.describe} rejects Nominal[#{other_type.class_name}] (could be NaN or fall outside)"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "FloatRange rejects #{other_type.class}"
+            )
+          end
+        end
+
+        def accepts_float_range_from_constant(self_type, constant, mode)
+          unless constant.value.is_a?(Float)
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "FloatRange rejects non-Float Constant"
+            )
+          end
+
+          if self_type.covers?(constant.value)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "Constant[#{constant.value}] is in #{self_type.describe}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Constant[#{constant.value}] outside #{self_type.describe}"
+            )
+          end
+        end
+
+        def accepts_float_range_from_float_range(self_type, other_range, mode)
+          if self_type.min <= other_range.min && other_range.canonical_max <= self_type.canonical_max
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "#{other_range.describe} ⊆ #{self_type.describe}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{other_range.describe} not contained in #{self_type.describe}"
+            )
+          end
+        end
+
         # `Difference[base, removed]` accepts another type X when the base accepts X *and* X's value set is
         # provably disjoint from `removed`. The disjointness test is the subtle part — it is NOT the same as
         # `removed.accepts(X)`, because `Nominal[String]` includes `""` even though `Constant[""]` does not
-        # "accept" `Nominal[String]`. The conservative rule here: we can prove disjointness only when X is
-        # itself a `Constant` carrier (compare values directly) or another `Difference` with the same
-        # removed value (already exhibits the disjointness). Any other shape — Nominal, Union, IntegerRange
-        # — could overlap the removed value, so the difference rejects it under gradual mode.
+        # "accept" `Nominal[String]`. The conservative rule here: we can prove disjointness only when X is a
+        # carrier whose value set is visibly apart from `removed` — a `Constant` (compare values directly),
+        # another `Difference` with the same removed value (already exhibits the disjointness), an
+        # `IntegerRange` that skips an Integer removed value, a `Tuple` whose fixed arity differs from a
+        # removed `Tuple`, or a `HashShape` with a required key a closed removed `HashShape` cannot hold. The
+        # last three cover the empty witnesses of `non-zero-int`, `non-empty-array[T]` and
+        # `non-empty-hash[K, V]`. Any other carrier — a Nominal above all — is no proof and the difference
+        # rejects it under gradual mode, even where its values happen to exclude `removed`. A Union or
+        # Intersection argument never reaches this rule whole: `accepts` splits it into members first.
         def accepts_difference(self_type, other_type, mode)
           base_result = accepts(self_type.base, other_type, mode: mode)
           return base_result if base_result.no?
@@ -651,9 +847,27 @@ module Rigor
             # Disjointness is monotonic over Intersection: if any member is provably disjoint from
             # `removed`, the meet is too.
             other_type.members.any? { |m| provably_disjoint_from_removed?(m, removed) }
+          when Type::IntegerRange
+            removed.is_a?(Type::Constant) && removed.value.is_a?(Integer) && !other_type.covers?(removed.value)
+          when Type::Tuple
+            # A Tuple's arity is fixed, so it shares no inhabitant with a Tuple of another arity — the
+            # zero-arity witness `non-empty-array[T]` removes included.
+            removed.is_a?(Type::Tuple) && removed.elements.size != other_type.elements.size
+          when Type::HashShape
+            hash_shape_excludes_removed?(other_type, removed)
           end
         end
 
+        # Every inhabitant of `shape` holds each of its required keys, and a closed `removed` shape holds no
+        # key outside its pairs, so one required key `removed` does not list makes the two disjoint. Against
+        # the closed `{}` witness `non-empty-hash[K, V]` removes, that is any required key; an optional key
+        # proves nothing, since the shape is inhabited without it.
+        def hash_shape_excludes_removed?(shape, removed)
+          return false unless removed.is_a?(Type::HashShape) && removed.closed?
+
+          shape.required_keys.any? { |key| !removed.pairs.key?(key) }
+        end
+
         # `Refined[base, predicate]` accepts another type X when the base accepts the *base* of X *and* X is
         # provably contained in the predicate's value set. The base check is delegated to
         # `accepts(self.base, X.base)` so handlers like `accepts_nominal` see Nominal-vs-Nominal and return
@@ -788,11 +1002,15 @@ module Rigor
 
         # HashShape{k1: T1, ...} accepts another HashShape when every required key of self is required on
         # the other side and Ti accepts Ui (depth covariant). Optional keys may be absent on the other side;
-        # when present, their values are checked. A closed self rejects known or possible extra keys. Other
-        # types are rejected; the converse direction (a Nominal accepting a HashShape) is handled by
+        # when present, their values are checked. A closed self rejects known extra keys, and answers at most
+        # `maybe` for an open source: `h = { a: 1 }; h.default = 0` reopens a shape whose key set is still
+        # exactly the literal's. Other types are rejected, except a `Hash` with a gradual arm (see
+        # {#gradual_hash?}); the converse direction (a Nominal accepting a HashShape) is handled by
         # `accepts_nominal` via projection.
         def accepts_hash_shape(self_type, other_type, mode)
           unless other_type.is_a?(Type::HashShape)
+            return gradual_hash_verdict(self_type, other_type, mode) if gradual_hash?(other_type)
+
             return Type::AcceptsResult.no(
               mode: mode,
               reasons: "HashShape does not accept #{other_type.class}"
@@ -803,8 +1021,6 @@ module Rigor
           return hash_shape_no(mode, "HashShape missing required keys: #{missing.inspect}") unless missing.empty?
 
           if self_type.closed?
-            return hash_shape_no(mode, "HashShape closed target rejects open source") if other_type.open?
-
             extra = other_type.pairs.keys - self_type.pairs.keys
             unless extra.empty?
               return hash_shape_no(mode, "HashShape closed target rejects extra keys: #{extra.inspect}")
@@ -812,9 +1028,59 @@ module Rigor
           end
 
           per_entry = hash_shape_entry_results(self_type, other_type, mode)
-          combine_arg_results(per_entry, mode)
+          result = combine_arg_results(per_entry, mode)
+          return result unless result.yes? && self_type.closed? && other_type.open?
+
+          unread_hash_maybe(mode, "HashShape closed target cannot check open source")
+        end
+
+        # A `Hash` nominal — directly or as the base of a `Difference` (`non-empty-hash[K, V]`) — that is raw or
+        # carries a `Dynamic` arm in a type argument. A hash literal with a `**splat` entry carries the arm by
+        # design, `Hash.new` filled key by key reads as the raw `Hash`, and a declared `Hash[Symbol, untyped]`
+        # is the author saying the hash may hold anything (the reading `MutationRejoin#regrowable_carrier?`
+        # gives a declared gradual arm). The runtime value may then hold exactly the record's keys, so a shape
+        # cannot reject it on the arm's account, the way `Hash[K, V]` accepts a raw `Hash` as maybe. A `Hash`
+        # subclass is not read: its entries need not be the record's (`HashWithIndifferentAccess` stores String
+        # keys).
+        def gradual_hash?(type)
+          nominal = type.is_a?(Type::Difference) ? type.base : type
+          nominal.is_a?(Type::Nominal) && nominal.class_name == "Hash" &&
+            (nominal.type_args.empty? || nominal.type_args.any? { |arg| gradual_arm?(arg) })
         end
 
+        # `maybe`, unless an argument without a gradual arm already rules the record out: a precise `K` that
+        # rejects a required key (`Hash[String, untyped]` never holds `:a`), or a precise `V` none of whose
+        # members a required key's type accepts.
+        def gradual_hash_verdict(self_type, other_type, mode)
+          nominal = other_type.is_a?(Type::Difference) ? other_type.base : other_type
+          key_type, value_type = nominal.type_args
+          missing = unholdable_keys(self_type, key_type, mode)
+          return hash_shape_no(mode, "Hash key type cannot hold required keys: #{missing.inspect}") if missing.any?
+
+          refused = refused_value_keys(self_type, value_type, mode)
+          return hash_shape_no(mode, "Hash value type refused for required keys: #{refused.inspect}") if refused.any?
+
+          unread_hash_maybe(mode, "HashShape cannot check #{other_type.describe(:short)}")
+        end
+
+        def unholdable_keys(self_type, key_type, mode)
+          return [] if key_type.nil? || gradual_arm?(key_type)
+
+          self_type.required_keys.select { |key| key_type.accepts(Type::Combinator.constant_of(key), mode: mode).no? }
+        end
+
+        def refused_value_keys(self_type, value_type, mode)
+          return [] if value_type.nil? || gradual_arm?(value_type)
+
+          members = ContentJoin.union_members(value_type)
+          self_type.required_keys.select do |key|
+            formal = self_type.pairs.fetch(key)
+            members.all? { |member| accepts(formal, member, mode: mode).no? }
+          end
+        end
+
+        def gradual_arm?(type) = ContentJoin.union_members(type).any?(Type::Dynamic)
+
         def hash_shape_entry_results(self_type, other_type, mode)
           self_type.pairs.filter_map do |key, formal|
             next unless other_type.pairs.key?(key)
@@ -936,7 +1202,7 @@ module Rigor
         def resolve_class(name)
           return nil unless name.is_a?(::String)
 
-          parts = name.delete_prefix("::").split("::")
+          parts = class_name_parts(name)
           return nil if parts.empty?
 
           mod = ::Object
@@ -950,7 +1216,16 @@ module Rigor
         rescue ::StandardError, ::ScriptError, ::SystemExit
           nil
         end
+
+        # #775 — the split of a class name is a pure function of the string, and the subtype check asks it
+        # twice per Nominal-vs-Nominal comparison (~370k times on the lib self-check) for the same few
+        # hundred names. Only the split is memoised; the constant walk above still runs every time, so a
+        # class loaded (or a spec constant removed) after the first ask is answered by the live tree.
+        def class_name_parts(name)
+          @class_name_parts[name] ||= name.delete_prefix("::").split("::").freeze
+        end
       end
+      @class_name_parts = {}
     end
   end
 end

data/lib/rigor/inference/block_auto_splat.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "multi_target_binder"
+
+module Rigor
+  module Inference
+    # The auto-splat half of {BlockParameterBinder}: given a block's positional parameter shape and the one
+    # value the receiver yields, it answers the positional table the block's names are bound from.
+    #
+    # Ruby blocks (NOT lambdas) spread a single yielded array-ish value across their positionals, and CRuby
+    # decides that on the PARAMETER LIST alone ({ParameterShape#splats?}) — never on the value. So the
+    # carrier only decides how precisely each position can be filled, and a carrier this module cannot
+    # decompose lowers the positions to `Dynamic[Top]` rather than cancelling the spread (issue #1116).
+    #
+    # Each member of the carrier (a union distributes; anything else is its own single member) contributes
+    # one {Table}, and {join} folds them into the answer:
+    #
+    # - a `Type::Tuple` spreads element-wise, leading positionals (required, then optional) from the head
+    #   and, with a rest present, trailing positionals from the tail with the rest absorbing the middle —
+    #   the split `MultiTargetBinder` applies to `a, *r, b = tuple`, so `|*r, v|` over `[K, V]` binds `v` to
+    #   `V`. A slot past the tuple is left unfilled and lands on `Dynamic[Top]`;
+    # - an `Array[T]` ({MultiTargetBinder.array_element_type}) binds `T` to every required and trailing
+    #   positional, `Dynamic[Top]` to every optional one (a short array hands it its default, not `nil`),
+    #   and `Array[T]` to a named rest. A short array pads the fixed positions with `nil` at runtime, so
+    #   those positions are reported optimistic (issue #1093);
+    # - an opaque array carrier — a raw `Array`, an `Array[untyped]` / `Array[top]`, a `Refined` /
+    #   `Difference` over either, or a `Dynamic` over any `Array` however precise — binds `Dynamic[Top]` to
+    #   every position: the floor `MultiTargetBinder` binds for the same undecomposable right-hand side, and
+    #   the reason `[1, 2].tap { |a, b| a.succ }` no longer reads `a` as the whole `Array` (issue #1116);
+    # - a bare `nil` binds `nil` to every position. `nil` has no `to_ary`, so CRuby passes it as the one
+    #   argument and `|a, b|` sees `nil, nil` — which is also what the wrap `[nil]` pads to, so the two
+    #   readings agree here, and {join} takes that `nil` back out of any position another member fills;
+    # - every other member takes the same `Dynamic[Top]` floor as the opaque one, and does NOT license the
+    #   spread on its own. It is the member the union knows least about, and joining it as a value would put
+    #   a nil-bearing element beside a nil-free one: `String#scan`'s `String | Array[String?]` yield joins a
+    #   capture's `String?` against the whole match's `String` and fires `call.possible-nil-receiver` on the
+    #   correlated-invariant `refinements[name.to_sym]`, which ADR-5 ranks above the precision.
+    #
+    # The spread needs at least one Tuple, `Array[T]` or opaque array member; a carrier with none of them
+    # ({#for} answers nil) leaves the binder's declared types alone, which binds the value to the first
+    # parameter and `Dynamic[Top]` after. So a lone value with no `to_ary` is NOT wrapped as `[value]` the
+    # way `a, b = value` wraps it: the one-value premise of auto-splat is the RBS block signature's arity,
+    # which nothing here can check against the actual yield, and a wrong wrap binds `nil` to a parameter the
+    # block receives a value in.
+    #
+    # See docs/internal-spec/inference-engine.md for the binding contract.
+    module BlockAutoSplat
+      # The positional part of a parameter list, as counts: all the auto-splat rule reads. An explicit
+      # `BlockParametersNode` list and a numbered-parameter block (`maximum` required positionals) both
+      # reduce to it, so the two spellings cannot drift.
+      ParameterShape = Data.define(:required, :optional, :post, :rest) do
+        def self.of(params_node)
+          new(required: params_node.requireds.size, optional: params_node.optionals.size,
+              post: params_node.posts.size, rest: !params_node.rest.nil?)
+        end
+
+        # The `_1` / `_2` form, read as the explicit list of `arity` required positionals.
+        def self.of_arity(arity)
+          new(required: arity, optional: 0, post: 0, rest: false)
+        end
+
+        def positional_count = required + optional + post
+
+        # CRuby's own condition (`vm_callee_setup_block_arg` / `setup_parameters_complex`): a block splats a
+        # lone array argument when it has a mandatory positional (`lead + post > 0`) or more than one
+        # optional, except a bare `|a|` (the iseq's `ambiguous_param0`). So `|k, *r|`, `|*r, v|`,
+        # `|a = 1, b = 2|` and the trailing-comma `|k,|` (Prism's `ImplicitRestNode`) splat, while `|*r|`,
+        # `|a = 1, *r|` and `|a, &b|` / `|a, k: 1|` do not.
+        def splats?
+          mandatory = required + post
+          return false unless mandatory.positive? || optional > 1
+
+          !(mandatory == 1 && optional.zero? && !rest)
+        end
+      end
+
+      # A positional table: the type per position, the positions bound optimistically, and the named rest's
+      # type (nil for the `Array[Dynamic[Top]]` default). One arm produces one; {join} folds them into one.
+      # Private as a name — {#for} hands the folded value out, and nothing outside constructs one.
+      Table = Data.define(:types, :optimistic_positions, :rest_type)
+      private_constant :Table
+
+      # The arm kinds that make a member an array as far as the spread is concerned, so that a union
+      # carrying one of them spreads even where its other members do not decompose.
+      ARRAY_CARRIER_ARMS = %i[tuple array opaque].freeze
+      private_constant :ARRAY_CARRIER_ARMS
+
+      module_function
+
+      # @param shape — the block's {ParameterShape}.
+      # @param carrier — the one value the receiver yields.
+      # @return the folded {Table}, or nil when no member is an array carrier and the
+      #   spread must leave the declared types alone.
+      def for(shape, carrier)
+        arms = arms_of(carrier)
+        return nil if arms.nil?
+
+        join(arms.map { |member, kind| table_for(shape, member, kind) })
+      end
+
+      def arms_of(carrier)
+        members = carrier.is_a?(Type::Union) ? carrier.members : [carrier]
+        arms = members.map { |member| [member, arm_of(member)] }
+        arms.any? { |_, kind| ARRAY_CARRIER_ARMS.include?(kind) } ? arms : nil
+      end
+
+      def arm_of(member)
+        return :tuple if member.is_a?(Type::Tuple)
+        return :array if MultiTargetBinder.array_element_type(member)
+        return :opaque if opaque_array_carrier?(member)
+        return :nil_value if nil_literal?(member)
+
+        :unknown
+      end
+
+      # A carrier that is an array the module may not decompose into per-position types: the raw `Array`, an
+      # `Array[untyped]` / `Array[top]`, a `Refined` / `Difference` over either, and a `Dynamic` over ANY
+      # carrier that would license the spread — `Dynamic[Array[Integer]]`, `Dynamic[[Integer, String]]`,
+      # `Dynamic[Array[Integer] | nil]` alike. {MultiTargetBinder.array_element_type} declines every
+      # `Dynamic` wrapper on purpose: the value is gradual, and projecting its static facet would hand each
+      # position a bare `T` that licenses the negative rules (issue #1093, ADR-5). That is a reason to floor
+      # the positions, not a reason to leave the whole value on the first parameter, so the facet decides
+      # only whether CRuby would splat.
+      def opaque_array_carrier?(type)
+        case type
+        when Type::Nominal then type.class_name == "Array"
+        when Type::Refined, Type::Difference then opaque_array_carrier?(type.base)
+        when Type::Dynamic then !arms_of(type.static_facet).nil?
+        else false
+        end
+      end
+
+      def table_for(shape, member, kind)
+        case kind
+        when :tuple then tuple_table(shape, member.elements)
+        when :array then array_table(shape, MultiTargetBinder.array_element_type(member))
+        when :nil_value then uniform_table(shape, member)
+        else uniform_table(shape, Type::Combinator.untyped)
+        end
+      end
+
+      # The split is mirrored rather than delegated to `MultiTargetBinder.decompose_tuple` because that one
+      # pads a missing slot with `Constant[nil]` and softens `X | nil`; a block slot past the tuple has
+      # always bound `Dynamic[Top]`. Without a rest the trailing positionals continue from the head (Ruby
+      # fills `|a, b = 1, c|` from the head when the tuple is long enough).
+      def tuple_table(shape, elements)
+        head = shape.required + shape.optional
+        posts = shape.post
+        tail_start = shape.rest ? [elements.size - posts, head].max : head
+        types = Array.new(head) { |i| elements[i] } + Array.new(posts) { |j| elements[tail_start + j] }
+        Table.new(types: types, optimistic_positions: [], rest_type: nil)
+      end
+
+      def array_table(shape, element)
+        required = shape.required
+        optional = shape.optional
+        posts = shape.post
+        Table.new(
+          types: Array.new(required) { element } + Array.new(optional) { Type::Combinator.untyped } +
+                 Array.new(posts) { element },
+          optimistic_positions: (0...required).to_a + ((required + optional)...(required + optional + posts)).to_a,
+          rest_type: Type::Combinator.nominal_of("Array", type_args: [element])
+        )
+      end
+
+      # One type for every position: the `Dynamic[Top]` floor of a member the module cannot decompose, or
+      # the `nil` a `nil` member hands each of them. The `nil` rest_type leaves a named rest on the binder's
+      # `Array[Dynamic[Top]]` default, which is right for both — CRuby gives `nil.tap { |a, *r| }` an empty
+      # `r`, and an opaque carrier says nothing about the leftovers.
+      def uniform_table(shape, type)
+        Table.new(types: Array.new(shape.positional_count) { type }, optimistic_positions: [], rest_type: nil)
+      end
+
+      # A single member's table is used as is. Across members, a position any member leaves unfilled (a slot
+      # past a short Tuple) or fills with `Dynamic[Top]` stays `Dynamic[Top]`, and a member's bare `nil`
+      # drops out of a position another member fills with a value, that position then being optimistic —
+      # `MultiTargetBinder`'s cross-member softening. A named rest joins only when every member supplies
+      # one; otherwise the binder's `Array[Dynamic[Top]]` default stands.
+      def join(tables)
+        types, softened = join_types(tables.map(&:types))
+        rests = tables.map(&:rest_type)
+        Table.new(
+          types: types,
+          optimistic_positions: (tables.flat_map(&:optimistic_positions) + softened).uniq,
+          rest_type: rests.include?(nil) ? nil : Type::Combinator.union(*rests)
+        )
+      end
+
+      # @return the joined table and the positions it softened.
+      def join_types(tables)
+        return [tables.first, []] if tables.size == 1
+
+        softened = []
+        joined = Array.new(tables.map(&:size).max) do |i|
+          column = tables.map { |table| table[i] }
+          next Type::Combinator.untyped if column.any? { |t| t.nil? || t == Type::Combinator.untyped }
+
+          firm = column.reject { |t| nil_literal?(t) }
+          next Type::Combinator.union(*column) if firm.empty? || firm.size == column.size
+
+          softened << i
+          Type::Combinator.union(*firm)
+        end
+        [joined, softened]
+      end
+
+      def nil_literal?(type) = type.is_a?(Type::Constant) && type.value.nil?
+
+      # {#for} is the whole surface; the arms and the fold are this module's own business, and keeping them
+      # off the singleton stops a caller reaching past the fold for one member's table.
+      private_class_method :arms_of, :arm_of, :opaque_array_carrier?, :table_for, :tuple_table, :array_table,
+                           :uniform_table, :join, :join_types, :nil_literal?
+    end
+  end
+end