rigortype 0.4.6 → 0.4.7

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

@@ -8,8 +8,10 @@ require_relative "../rbs_type_translator"
 require_relative "../external_ancestor_resolution"
 require_relative "../void_origin"
 require_relative "../optimistic_origin"
+require_relative "argument_distribution"
 require_relative "overload_selector"
 require_relative "self_substitute"
+require_relative "../../run_scoped_slots"
 
 module Rigor
   module Inference
@@ -33,8 +35,8 @@ module Rigor
       # type-parameter names (`Array` -> `[:Elem]`, `Hash` -> `[:K, :V]`, ...) to build a substitution map;
       # that map is then threaded through {RbsTypeTranslator} so a return type like `::Array[Elem]`
       # resolves to `Nominal["Array", [Integer]]` rather than degrading the variable to `Dynamic[Top]`.
-      # When arities mismatch (raw receiver, partial generics) the map is left empty and free variables
-      # degrade as before.
+      # A raw receiver, or one with more arguments than the class declares, leaves the map empty and free
+      # variables degrade as before; fewer arguments bind the declared prefix (#1121).
       #
       # Slice 5 phase 1 projects shape-carrying receivers onto their underlying nominal so the existing
       # dispatch + substitution machinery works without duplication: `Tuple[Integer, String]` dispatches as
@@ -44,13 +46,14 @@ module Rigor
       #
       # Remaining limitations:
       #
-      # * Keyword arguments reach `args` only as one trailing hash entry and are not matched against keyword
-      #   parameters, so overloads with required keywords are skipped.
-      # * Method-level type parameters bind only from two positions: the block return type (Slice 6 phase C)
-      #   and a positional parameter whose declared type is EXACTLY a type variable (issue #303 —
+      # * Keyword arguments reach `args` as one trailing hash entry; the selector matches it against keyword
+      #   parameters when the call's last argument is a keyword hash (#1727).
+      # * Method-level type parameters bind from the block return type (Slice 6 phase C) and from a
+      #   positional parameter whose declared type is EXACTLY a type variable (issue #303 —
       #   `def foo[T]: (T) -> T` binds `T` from the first argument, and carries it into a generic return
-      #   such as `-> Array[T]`). A variable reachable only through a container position (`Array[T] arg`),
-      #   a rest positional (`*T`), or a keyword parameter is still unbound and degrades to `Dynamic[Top]`.
+      #   such as `-> Array[T]`), plus a `Range[A]` element (#834). A variable reachable only through other
+      #   container positions (`Array[T] arg`), a rest positional (`*T`), or a keyword parameter is still
+      #   unbound and degrades to `Dynamic[Top]`.
       #   A block-return variable that a parameter also names takes the value class the argument and the
       #   block share once the call passes an argument, or stays unbound when they share none (see
       #   {compose_block_type_vars}).
@@ -681,7 +684,7 @@ module Rigor
 
           # The same one-slot memo shape as {#core_stdlib_memo}; see there for why it is one slot keyed
           # on the discovery index's identity, and what a recording run may store in it.
-          MIXIN_ANCESTOR_MEMO_KEY = :__rigor_mixin_ancestor_dispatch__
+          MIXIN_ANCESTOR_MEMO_KEY = RunScopedSlots.register(:__rigor_mixin_ancestor_dispatch__)
           private_constant :MIXIN_ANCESTOR_MEMO_KEY
 
           def mixin_ancestor_memo(environment, scope)
@@ -855,7 +858,7 @@ module Rigor
           # the measurement. A `Scope` hands each analysed file its own discovery index, so an
           # identity-keyed store would pin every file's index, and every RBS definition resolved
           # against it, for the length of the run.
-          CORE_STDLIB_ANCESTOR_MEMO_KEY = :__rigor_core_stdlib_ancestor_dispatch__
+          CORE_STDLIB_ANCESTOR_MEMO_KEY = RunScopedSlots.register(:__rigor_core_stdlib_ancestor_dispatch__)
           private_constant :CORE_STDLIB_ANCESTOR_MEMO_KEY
 
           def core_stdlib_memo(environment, scope)
@@ -1086,7 +1089,42 @@ module Rigor
               block_required: !block_type.nil?,
               environment: environment
             )
-            return nil if candidates.empty?
+            if candidates.empty?
+              return unselected_return(method_definition, self_type, instance_type, type_vars, args, block_type,
+                                       scope, call_node, call_site, environment, keywords_last)
+            end
+
+            selected_return(candidates, method_definition, self_type, instance_type, type_vars, args, block_type, scope,
+                            call_node, call_site, environment, keywords_last)
+          end
+
+          # Issue #2429 — a block call no overload matches, whose block overloads the arity fallback cannot decide
+          # between, selects nothing. An argument union may still select per value (#2379): `S.h(flag ? "s" : 1) { }`
+          # takes the `String` arm for `"s"` and the `Integer` arm for `1`. Otherwise the tier declines (nil), so a
+          # later tier, such as the project's own definition of the method, answers.
+          # rubocop:disable Metrics/ParameterLists
+          def unselected_return(method_definition, self_type, instance_type, type_vars, args, block_type, scope,
+                                call_node, call_site, environment, keywords_last)
+            # rubocop:enable Metrics/ParameterLists
+            return nil if keywords_last
+
+            distributed = distributed_argument_return(method_definition, nil, self_type, instance_type, type_vars, args,
+                                                      block_type, scope, call_node, call_site, environment)
+            distributed.equal?(NOT_DISTRIBUTED) ? nil : distributed
+          end
+
+          # The return of the overloads the call selected: per argument value where a union or supertype argument
+          # selects more than `candidates` ({#distributed_argument_return}), else their join.
+          # rubocop:disable Metrics/ParameterLists
+          def selected_return(candidates, method_definition, self_type, instance_type, type_vars, args, block_type,
+                              scope, call_node, call_site, environment, keywords_last)
+            # rubocop:enable Metrics/ParameterLists
+            if candidates.size == 1 && !keywords_last
+              distributed = distributed_argument_return(method_definition, candidates.first, self_type, instance_type,
+                                                        type_vars, args, block_type, scope, call_node, call_site,
+                                                        environment)
+              return distributed unless distributed.equal?(NOT_DISTRIBUTED)
+            end
 
             record_dispatch_provenance(method_definition, candidates.first, scope, call_node, call_site)
             join_candidate_returns(
@@ -1169,6 +1207,75 @@ module Rigor
             end
           end
 
+          # Issue #2379 — a positional argument selects its overload per runtime value, as the receiver does
+          # (`dispatch` distributes a union receiver). Selecting once for the whole argument took the first overload
+          # it `maybe`-matched: `Integer#+` with an `Integer | Float` argument read `(Integer) -> Integer`, and with a
+          # `Numeric` one as well. So a precise union argument selects per member ({ArgumentDistribution.lists}; a
+          # member no overload takes keeps the first-overload fallback, as a non-matching argument does), and a
+          # nominal argument wider than the selected overload's parameter takes every strictly typed overload it
+          # overlaps ({OverloadSelector.contested_matches}). The returns join as a plain union, and a return that does
+          # not translate declines the call (nil), as the #521 join does. Union arguments that combine past the list
+          # limit answer `Dynamic[top]`: neither the first overload nor any narrower reading is sound there. When
+          # every list selects `chosen` alone the call answers {NOT_DISTRIBUTED} and reads as before, so a precise
+          # argument keeps its answer; so does a call holding an imprecise argument (the #521 join owns it) or a splat.
+          # rubocop:disable Metrics/ParameterLists
+          def distributed_argument_return(method_definition, chosen, self_type, instance_type, type_vars, args,
+                                          block_type, scope, call_node, call_site, environment)
+            # rubocop:enable Metrics/ParameterLists
+            selector = { self_type: self_type.is_a?(Type::Dynamic) ? self_type.static_facet : self_type,
+                         instance_type: instance_type, type_vars: type_vars, block_required: !block_type.nil?,
+                         environment: environment }
+            return NOT_DISTRIBUTED unless distributable_arguments?(method_definition, args, call_node)
+
+            lists = ArgumentDistribution.lists(args)
+            return Type::Combinator.untyped if lists.equal?(ArgumentDistribution::OVER_LIMIT)
+
+            per_list = argument_distribution_matches(method_definition, chosen, args, lists, selector)
+            return NOT_DISTRIBUTED if per_list.nil?
+
+            overloads = per_list.flat_map(&:last).uniq
+            if overloads.size == 1
+              record_dispatch_provenance(method_definition, overloads.first, scope, call_node, call_site)
+            end
+            returns = per_list.flat_map do |arg_types, matches|
+              matches.map do |method_type|
+                join_candidate_returns(
+                  [method_type],
+                  method_definition: method_definition,
+                  self_type: self_type, instance_type: instance_type, type_vars: type_vars,
+                  args: arg_types, block_type: block_type, scope: scope, call_node: call_node, call_site: call_site,
+                  alias_expander: environment.rbs_loader
+                )
+              end
+            end
+            returns.any?(&:nil?) ? nil : Type::Combinator.union(*returns.uniq)
+          end
+
+          # Each argument list (`lists`, from {ArgumentDistribution.lists}, or the call's own) with the overloads it
+          # selects, or nil when every list selects `chosen` alone. `selector` holds {OverloadSelector}'s keyword
+          # inputs.
+          def argument_distribution_matches(method_definition, chosen, args, lists, selector)
+            return nil if lists.nil? && args.none?(Type::Nominal)
+
+            per_list = (lists || [args]).map do |arg_types|
+              picked = chosen if arg_types.equal?(args)
+              picked ||= OverloadSelector.select(method_definition, arg_types:, **selector)
+              # #2429's block fallback may answer no overload; the call then reads as it did undistributed.
+              return nil unless picked
+
+              contested = OverloadSelector.contested_matches(method_definition, picked, arg_types:, **selector)
+              [arg_types, contested || [picked]]
+            end
+            per_list unless per_list.all? { |_, matches| matches.size == 1 && matches.first.equal?(chosen) }
+          end
+
+          # Only a call with overloads to choose between and precise arguments it spells out one by one may select
+          # differently per argument value: an imprecise argument is the #521 join's, a splat hides the positions.
+          def distributable_arguments?(method_definition, args, call_node)
+            method_definition.method_types.size > 1 && !args.empty? &&
+              !ImpreciseArgument.any_in?(args, false) && !splat_indices(call_node, args)
+          end
+
           def join_distributed_returns(returns, keywords)
             return nil if returns.any?(&:nil?)
 
@@ -1412,11 +1519,24 @@ module Rigor
           # to {#shared_value_class} where both sides have one, and to `Dynamic[top]` otherwise. The key
           # stays in the map either way so {#compose_arg_type_vars} does not bind the variable from the
           # argument alone.
+          #
+          # A block return spelled as the variable beside falsey arms (`(nil | false | U)`, `U?`) solves the
+          # variable from the block's type less those arms ({#strip_falsey_arms}): `filter_map` keeps only
+          # the block's truthy values, so a block answering `String | nil` binds `U` to `String`. The strip
+          # trusts the declared method to discard those values, so a receiver class whose Ruby source
+          # defines the method itself leaves the variable unbound: `def filter_map(&b) = map(&b).compact`
+          # under an `include Enumerable[Integer]` declaration keeps `false`, and `Array[true]` would fold
+          # `b.last == false` always-falsey on correct code.
           def compose_block_type_vars(method_type, type_vars, block_type, args, scope:, call_node:, call_site:)
             return type_vars if block_type.nil?
 
             block_var_name = method_type_block_return_variable(method_type)
             return type_vars if block_var_name.nil?
+
+            arms = block_return_falsey_arms(method_type)
+            return type_vars if arms.any? && project_redefined?(scope, call_site)
+
+            block_type = strip_falsey_arms(block_type, arms)
             return type_vars.merge(block_var_name => block_type) unless
               argument_reaches_variable?(method_type, block_var_name, args)
 
@@ -1751,14 +1871,78 @@ module Rigor
           end
 
           def block_return_variable(method_type)
+            return_type = block_return_type(method_type)
+            return return_type if return_type.is_a?(RBS::Types::Variable)
+
+            falsey_armed_variable(return_type)&.first
+          end
+
+          def block_return_type(method_type)
             block = method_type.respond_to?(:block) ? method_type.block : nil
             return nil if block.nil?
 
             fun = block.type
-            return nil unless fun.respond_to?(:return_type)
+            fun.respond_to?(:return_type) ? fun.return_type : nil
+          end
+
+          # The falsey arms ({#falsey_armed_variable}) the block's declared return spells beside its variable;
+          # empty for a bare variable.
+          def block_return_falsey_arms(method_type)
+            falsey_armed_variable(block_return_type(method_type))&.last || EMPTY_FALSEY_ARMS
+          end
+
+          EMPTY_FALSEY_ARMS = [].freeze
+          private_constant :EMPTY_FALSEY_ARMS
+
+          # A block return that is one type variable beside `nil` and/or `false` and nothing else —
+          # `Enumerable#filter_map`'s `(nil | false | U)`, or `U?` — as `[variable, arms]`, the arms a subset
+          # of `[:nil, :false]`. Anything else, `bool` among them, is nil: a block return must only lose
+          # values the method itself discards, and a `false`-only arm has no carrier that removes `false`
+          # alone from a `Dynamic` block type, so it declines too.
+          def falsey_armed_variable(return_type)
+            members =
+              case return_type
+              when RBS::Types::Optional then [return_type.type, RBS::Types::Bases::Nil.new(location: nil)]
+              when RBS::Types::Union then return_type.types
+              else return nil
+              end
+            variables, arms = members.partition { |member| member.is_a?(RBS::Types::Variable) }
+            return nil unless variables.size == 1
 
-            return_type = fun.return_type
-            return_type.is_a?(RBS::Types::Variable) ? return_type : nil
+            arm_names = arms.map { |arm| falsey_arm_name(arm) }
+            return nil if arm_names.include?(nil) || !arm_names.include?(:nil)
+
+            [variables.first, arm_names.uniq]
+          end
+
+          def falsey_arm_name(arm)
+            case arm
+            when RBS::Types::Bases::Nil then :nil
+            when RBS::Types::Literal then arm.literal == false ? :false : nil # rubocop:disable Lint/BooleanSymbol
+            end
+          end
+
+          # The block's type less the falsey values the declared return spells beside the variable: its
+          # truthy fragment for `nil | false`, its non-nil fragment for `nil` alone. A `Dynamic` block type
+          # passes through unchanged, so an untyped block still binds `Dynamic[top]`. A block that answers
+          # only the stripped values binds `bot`, so `filter_map { nil }` is `Array[bot]`: an Array that
+          # holds no element.
+          # Whether the receiver class's Ruby source defines the dispatched method, the probe
+          # {#arg_binding_permitted?} also reads. Without a scope there is no discovery to consult.
+          def project_redefined?(scope, call_site)
+            return false if scope.nil?
+
+            class_name, method_name, kind = call_site
+            return false if method_name.nil?
+
+            scope.discovered_method?(class_name, method_name, kind)
+          end
+
+          def strip_falsey_arms(block_type, arms)
+            return block_type if arms.empty?
+            return Narrowing.narrow_truthy(block_type) if arms.include?(:false) # rubocop:disable Lint/BooleanSymbol
+
+            Narrowing.narrow_non_nil(block_type)
           end
 
           # ----- block parameter probe (Phase C sub-phase 1) -----
@@ -1862,7 +2046,9 @@ module Rigor
               instance_type: instance_type,
               type_vars: type_vars,
               block_required: true,
-              environment: environment
+              environment: environment,
+              # A call no overload matches binds no block parameter from the return path's block fallback (#2429).
+              block_fallback: false
             )
             return [] unless method_type
 
@@ -1940,7 +2126,7 @@ module Rigor
             # rubocop:enable Metrics/ParameterLists
             unless FacetDistribution.faceted?(arg_types)
               return OverloadSelector.select_declared(method_definition, arg_types, selector_self, instance_type,
-                                                      type_vars, block_required, environment, true, true, splats)
+                                                      type_vars, block_required, environment, true, true, splats, false)
             end
 
             facet_matches(method_definition, arg_types, selector_self, instance_type, type_vars, block_required,
@@ -1960,7 +2146,7 @@ module Rigor
               # The fallback list (`member` false) answers every gradual match rather than the strict pass's pick.
               OverloadSelector.select_declared(method_definition, list, selector_self, instance_type, type_vars,
                                                block_required, environment, member || :gradual, keywords_last,
-                                               splats)
+                                               splats, false)
             end
           end
 

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

@@ -148,7 +148,7 @@ module Rigor
 
         # Runs the actual reduction, guarded by the rescue harness and the magnitude cap. Empty-collection
         # semantics match Ruby: `[].reduce(s, :op) == s` (seed form) and `[].reduce(:op) == nil` (no-seed
-        # form → declines so the nominal fold's no-nil contract stands; see `fold_result`).
+        # form → declines so the nominal fold's no-nil contract stands; see the class comment).
         def execute_constant_reduce(members, operator, seed_value, seed_present)
           result =
             if seed_present

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

@@ -14,8 +14,8 @@ module Rigor
       # * `new(str)` / `new(str, opts)` — constructs a Regexp at fold time when the pattern argument is a
       #   `Constant[String]`. The optional second argument may be a `Constant[Integer]` (flag bits), a
       #   `Constant[true/false]` (IGNORECASE shorthand), or absent. Returns `Constant[Regexp]`.
-      # * `compile(str)` / `compile(str, opts)` — `Regexp.compile` is a documented alias of `Regexp.new`
-      #   (same C entry point, `rb_reg_s_new`); shares `fold_new` verbatim.
+      # * `compile(str)` / `compile(str, opts)` — `Regexp.compile` is a documented alias of `Regexp.new`;
+      #   shares `fold_new` verbatim.
       # * `union(*patterns)` / `union(array)` — builds the combined pattern at inference time when every
       #   element is a `Constant[String]` or `Constant[Regexp]`. Delegates to the real `Regexp.union` so the
       #   zero-arg (`/(?!)/`), single-array-argument, and pre-built-Regexp-argument forms all match Ruby's

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

@@ -67,8 +67,8 @@ module Rigor
           projected_self(class_name, receiver_args)
         end
 
-        # Nil when every argument widens to the bare `Dynamic[top]`: `Hash[untyped, untyped]` says nothing
-        # the raw `Hash` does not.
+        # Nil when every argument widens to untyped: a `Hash` of untyped keys and values says nothing the
+        # raw `Hash` does not.
         def projected_self(class_name, receiver_args)
           type_args = receiver_args.map { |arg| deep_widen(arg) }
           return nil if type_args.all? { |arg| untyped?(arg) }

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

@@ -13,17 +13,19 @@ module Rigor
       #
       # === Supported methods
       #
-      # * `Set[]` — variadic constructor; each argument must be a `Constant[T]`. Returns `Constant[Set]`.
+      # * `Set[]` — variadic constructor. Returns `Constant[Set]` when every argument is a `Constant[T]`, and a
+      #   typed `Set` otherwise.
       # * `Set.new` — zero-argument form; returns `Constant[Set.new]`.
-      # * `Set.new(tuple)` — the argument must be a `Tuple` whose every element is a `Constant[T]`. Returns
-      #   `Constant[Set]`.
+      # * `Set.new(tuple)` — a `Tuple` argument. Returns `Constant[Set]` when every element is a `Constant[T]`,
+      #   and a typed `Set` otherwise.
       #
       # === Non-constant / unsupported cases
       #
       # Returns `nil` (deferring to the next dispatcher tier) when:
       # - the receiver is not `Singleton[Set]`,
       # - the method is not `[]` or `new`,
-      # - any argument is non-constant or structurally opaque.
+      # - the call is splatted or carries a block, or its `new` argument is not a `Tuple` or an `Array` / `Set`
+      #   carrier.
       module SetFolding
         module_function
 
@@ -86,9 +88,9 @@ module Rigor
 
         # `Nominal[Set, [E]]`, `E` the members widened as an `Array.new` fill is (value pins dropped, a literal
         # container widened to its nominal) joined with a `Dynamic[top]` floor. The floor is the conservative half:
-        # nothing widens a Set's element when the program mutates it (`add`, `<<`, `merge`, `replace`, `clear`
-        # then `<<`, a callee that fills it), so the classes the set was built with are not a claim about what it
-        # holds later, and a read of the element must not report on them (#2278).
+        # the mutation seams ({SetMutation}, #2294) see one store at a time, so the classes the set was built with
+        # are not a claim about what it holds later, and a read of the element must not report on them (#2278). The
+        # floor is also what lets those seams re-grow the set.
         def typed_set(types)
           return nil if types.empty?
 

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

@@ -194,6 +194,7 @@ module Rigor
           Type::Tuple => :dispatch_tuple,
           Type::HashShape => :dispatch_hash_shape,
           Type::Nominal => :dispatch_nominal_size,
+          Type::Constant => :dispatch_constant_set,
           Type::Difference => :dispatch_difference,
           Type::Refined => :dispatch_refined,
           Type::Intersection => :dispatch_intersection,
@@ -302,9 +303,38 @@ module Rigor
               when :flatten then array_nominal_flatten(nominal, args)
               when :compact then array_nominal_compact(nominal, args)
               end
+            when "Set"
+              set_nominal_algebra(nominal, method_name, args)
             end
           end
 
+          # The Set algebra that returns a new Set holding both operands' elements (issue #2294). RBS declares each
+          # as `(_Each[A]) -> Set[A]`, the receiver's element alone, so `ARGV.to_set | [1]` read `Set[String]` and a
+          # read of its `1` reported on correct code. The result is `Set[E | F]`, `F` the argument's elements with
+          # their value pins dropped ({SetMutation.element_types}).
+          SET_UNION_ALGEBRA = %i[| union + ^].to_set.freeze
+          private_constant :SET_UNION_ALGEBRA
+
+          def set_nominal_algebra(nominal, method_name, args)
+            return nil unless SET_UNION_ALGEBRA.include?(method_name) && args.size == 1
+
+            receiver = nominal.type_args.size == 1 ? nominal.type_args.first : Type::Combinator.untyped
+            added = Inference::SetMutation.element_types(args.first).map { |t| MethodDispatcher.array_new_element(t) }
+            Type::Combinator.nominal_of("Set", type_args: [Type::Combinator.union(receiver, *added)])
+          end
+
+          # The same algebra on a constant-folded Set whose argument is not constant (two constants fold upstream in
+          # {ConstantFolding}): the receiver's members and the argument's elements, typed as #2290 types a
+          # `Set[...]` literal over non-constant members ({SetFolding.typed_set}).
+          def dispatch_constant_set(constant, method_name, args)
+            return nil unless SET_UNION_ALGEBRA.include?(method_name) && args.size == 1
+            return nil unless Inference::SetMutation.constant?(constant)
+
+            members = constant.value.map { |v| Type::Combinator.constant_of(v) }
+            SetFolding.typed_set(members + Inference::SetMutation.element_types(args.first)) ||
+              Type::Combinator.nominal_of("Set", type_args: [Type::Combinator.untyped])
+          end
+
           # `Integer#to_s` / `Integer#inspect` (#993) on a bare `Nominal[Integer]` receiver, ahead of the
           # existing `:*` binary fold. `#inspect` takes no argument and matches `#to_s()` byte for byte, so
           # it routes through the same no-arg branch.
@@ -317,7 +347,7 @@ module Rigor
           end
 
           # `decimal-int-string`'s predicate (`/\A-?\d+\z/`) admits the optional sign, so — unlike the
-          # `IntegerRange#to_s` tier above, which declines a signed range because it cannot yet prove the
+          # `IntegerRange#to_s` tier below, which declines a signed range because it cannot yet prove the
           # sign is absent — a bare `Integer` (sign completely unknown) still reaches it for the base-10
           # case: base 10 is Ruby's default sign-and-digits grammar for every Integer. Any other base,
           # known or not statically known, drops to `non-empty-string`: `to_s(base)` never returns `""`,
@@ -422,14 +452,29 @@ module Rigor
           # Resolves the element type of a flattened `Array[element]`. Each `Array[U]` nesting level
           # contributes `U`; the per-level element types are unioned. `depth < 0` recurses without bound;
           # `depth == 0` stops (Ruby's `flatten(0)` is a no-op copy and returns the element unchanged).
+          #
+          # Issue #2427 — a `Tuple` element is an Array too and contributes the union of its own elements, each
+          # flattened one level deeper, and so does a `Tuple` member of a `Union` element. `ARGV.map { |x| [x] }`
+          # is `Array[[String]]`, and returning its `[String]` element unchanged made `.flatten.first.upcase`
+          # report `undefined method 'upcase' for [String]` on code Ruby runs.
+          #
+          # A nominal `Array[U]` member of a `Union` element is kept. RBS's `String#scan(Regexp)` answers
+          # `Array[String | Array[String?]]`, the `?` standing for an optional group, and flattening that member
+          # turned the idiomatic `str.scan(/k = (.+)/).flatten.map(&:strip)` into a `possible-nil-receiver` for a
+          # group that always matches.
           def flatten_nominal_element(element, depth)
             return element if depth.zero?
-            return element unless array_nominal?(element)
 
-            inner = element.type_args.first
-            return element if inner.nil?
-
-            flatten_nominal_element(inner, depth - 1)
+            case element
+            when Type::Tuple
+              Type::Combinator.union(*element.elements.map { |inner| flatten_nominal_element(inner, depth - 1) })
+            when Type::Union
+              Type::Combinator.union(*element.members.map do |member|
+                member.is_a?(Type::Tuple) ? flatten_nominal_element(member, depth) : member
+              end)
+            else
+              array_nominal?(element) ? flatten_nominal_element(element.type_args.first, depth - 1) : element
+            end
           end
 
           def array_nominal?(type)
@@ -472,7 +517,7 @@ module Rigor
           # leading sign. Base 10 is Ruby's decimal-literal grammar, so the result lifts to
           # `decimal-int-string`. Signed ranges fall through entirely (the result could carry a `-` sign
           # that `decimal-int-string` alone would need a sign proof for, matching the
-          # `Nominal[Integer]` tier's own signed-base-10 carve-out below).
+          # `Nominal[Integer]` tier's own signed-base-10 carve-out above).
           #
           # #1004 — every other base (a different literal, such as 8 or 16, or a value that is not
           # statically known) does NOT lift to `octal-int-string` / `hex-int-string`: those refinements'
@@ -621,10 +666,10 @@ module Rigor
             Type::Combinator.positive_int
           end
 
-          # Predicate-subset projections over a `Refined[base, predicate]` receiver. Today the catalogue is
-          # the String case-normalisation pair: `s.downcase` over a `lowercase-string` receiver folds to
-          # the same carrier (already lowercase), and `s.upcase` lifts a `lowercase-string` to
-          # `uppercase-string`. Symmetric rules apply with the predicates swapped. Numeric-string
+          # Predicate-subset projections over a `Refined[base, predicate]` receiver. The catalogue is
+          # `REFINED_STRING_PROJECTIONS`, led by the String case-normalisation pair: `s.downcase` over a
+          # `lowercase-string` receiver folds to the same carrier (already lowercase), and `s.upcase` lifts a
+          # `lowercase-string` to `uppercase-string`. Symmetric rules apply with the predicates swapped. Numeric-string
           # idempotence over `#downcase` / `#upcase` is also recognised because a numeric string equals its
           # own case-normalisation.
           #
@@ -747,7 +792,7 @@ module Rigor
           # Compute the bounded-integer meet of two or more `IntegerRange` carriers. We compare via the
           # numeric `lower` / `upper` accessors (`-Float::INFINITY` / `Float::INFINITY` for the symbolic
           # ends), then map back to the symbolic-bound representation `IntegerRange.new` expects. The
-          # disjoint-meet case cannot arise from sound member-wise projections in v0.0.4 but is guarded
+          # disjoint-meet case cannot arise from sound member-wise projections but is guarded
           # defensively to keep the carrier total.
           def narrow_integer_ranges(ranges)
             numeric_low = ranges.map(&:lower).max
@@ -1204,15 +1249,32 @@ module Rigor
             Type::Combinator.tuple_of(*tuple.elements, *other.elements)
           end
 
-          # `tuple.compact` — removes every element that is `Constant[nil]`. Folds only when every element
-          # is a `Constant` (so the nil set is decidable). Mixed-shape elements decline so the RBS tier
-          # widens.
+          # `tuple.compact` — removes every element that is `Constant[nil]`. When every element is a
+          # `Constant` the nil set is decidable and the result is the exact Tuple of the kept elements.
+          # Otherwise an element that may be nil leaves the arity unknown, so the result is `Array[E]` with
+          # `E` the elements' union minus its `nil` constituent (#2519) — never a fixed-arity Tuple. When
+          # no element carries a `nil` constituent there is nothing to strip and the method declines so
+          # the RBS tier answers (an element such as `Dynamic[top]` may still be nil at runtime, so the
+          # Tuple is not kept either).
           def tuple_compact(tuple, _method_name, args)
             return nil unless args.empty?
-            return nil unless tuple.elements.all?(Type::Constant)
 
-            kept = tuple.elements.reject { |e| e.is_a?(Type::Constant) && e.value.nil? }
-            Type::Combinator.tuple_of(*kept)
+            if tuple.elements.all?(Type::Constant)
+              kept = tuple.elements.reject { |e| e.value.nil? }
+              return Type::Combinator.tuple_of(*kept)
+            end
+
+            tuple_compact_widened(tuple.elements)
+          end
+
+          def tuple_compact_widened(elements)
+            stripped = elements.map { |e| strip_nil_constituent(e) }
+            return nil if stripped.zip(elements).all? { |s, e| s.equal?(e) }
+
+            element = Type::Combinator.union(*stripped)
+            return Type::Combinator.tuple_of if element.is_a?(Type::Bot)
+
+            Type::Combinator.nominal_of("Array", type_args: [element])
           end
 
           # `uniq` (no block) → `Tuple` of the first occurrence of each distinct value. Folds only when
@@ -1293,7 +1355,8 @@ module Rigor
           end
 
           # `tuple.take(n)` — returns the first n elements as a new Tuple. The argument must be a
-          # `Constant[Integer]`. n <= 0 returns the empty Tuple; n >= size returns the full receiver.
+          # `Constant[Integer]`. `n == 0` returns the empty Tuple, a negative `n` declines, and `n >= size`
+          # returns the full receiver.
           def tuple_take(tuple, _method_name, args)
             n = non_negative_count_arg(args)
             return nil if n.nil?
@@ -1919,7 +1982,7 @@ module Rigor
           # `shape.values_at(:a, :b, ...)` with a list of static keys. Returns a `Tuple` whose per-position
           # values are the per-key value types (`Constant[nil]` for missing keys, mirroring Ruby's runtime
           # behaviour). A computed key takes the nil-bearing step {#hash_dig_step} gives it; the call falls
-          # through when any step does (a computed key on an open shape).
+          # through when any step does (a computed key on an open or empty shape).
           def hash_values_at(shape, _method_name, args)
             return nil if args.empty?
 

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

@@ -20,7 +20,6 @@ module Rigor
       #
       # Centralising both here keeps the receiver-shape and constant-unwrap knowledge in one place: if
       # `Type::Singleton` or `Type::Constant` ever changes shape, there is a single edit rather than nine.
-      # The per-tier fold bodies stay where they are — only the shared gate moves.
       module SingletonFolding
         module_function