rigortype 0.1.18 → 0.1.19

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

@@ -98,7 +98,8 @@ module Rigor
           uniq: :tuple_uniq,
           index: :tuple_find_index,
           find_index: :tuple_find_index,
-          rindex: :tuple_rindex
+          rindex: :tuple_rindex,
+          flatten: :tuple_flatten
         }.freeze
 
         HASH_SHAPE_HANDLERS = {
@@ -228,15 +229,8 @@ module Rigor
           end
 
           def dispatch_nominal_size(nominal, method_name, args)
-            if nominal.class_name == "String" && args.size == 1
-              string_binary = dispatch_string_binary_from_arg(method_name, args.first)
-              return string_binary if string_binary
-            end
-
-            if nominal.class_name == "Integer" && args.size == 1
-              integer_binary = dispatch_integer_binary_from_arg(method_name, args.first)
-              return integer_binary if integer_binary
-            end
+            projection = nominal_projection(nominal, method_name, args)
+            return projection if projection
 
             return nil unless args.empty?
 
@@ -246,6 +240,106 @@ module Rigor
             Type::Combinator.non_negative_int
           end
 
+          # Arg-/method-driven precision projections for a `Nominal`
+          # receiver, consulted ahead of the no-arg size tier. Each
+          # branch gates on the class name first so unrelated nominals
+          # skip the work. Returns nil when no projection applies.
+          def nominal_projection(nominal, method_name, args)
+            case nominal.class_name
+            when "String"
+              dispatch_string_binary_from_arg(method_name, args.first) if args.size == 1
+            when "Integer"
+              dispatch_integer_binary_from_arg(method_name, args.first) if args.size == 1
+            when "Array"
+              case method_name
+              when :flatten then array_nominal_flatten(nominal, args)
+              when :compact then array_nominal_compact(nominal, args)
+              end
+            end
+          end
+
+          # `Array[T]#compact` — `compact` removes every `nil` element,
+          # so the result element type is `T` with its `nil` constituent
+          # stripped (`Array[Node?]#compact` → `Array[Node]`). Mirrors
+          # the `Tuple#compact` constant fold for the generic element
+          # case. Declines when the receiver carries no type argument
+          # (the RBS `Array[untyped]` answer is already maximal) or when
+          # `T` has no `nil` constituent to remove (the result equals the
+          # receiver, so the RBS tier's answer is already precise).
+          def array_nominal_compact(nominal, args)
+            return nil unless args.empty?
+
+            element = nominal.type_args&.first
+            return nil if element.nil?
+
+            stripped = strip_nil_constituent(element)
+            return nil if stripped.equal?(element)
+
+            Type::Combinator.nominal_of("Array", type_args: [stripped])
+          end
+
+          # Removes the `nil` constituent from a (possibly union) type,
+          # returning the same object when there is nothing to remove so
+          # callers can detect the no-op cheaply. Kept local to the
+          # dispatch tier to avoid a dependency on the narrowing module.
+          def strip_nil_constituent(type)
+            case type
+            when Type::Constant
+              type.value.nil? ? Type::Combinator.bot : type
+            when Type::Nominal
+              type.class_name == "NilClass" ? Type::Combinator.bot : type
+            when Type::Union
+              kept = type.members.map { |m| strip_nil_constituent(m) }
+              return type if kept.zip(type.members).all? { |k, m| k.equal?(m) }
+
+              Type::Combinator.union(*kept)
+            else
+              type
+            end
+          end
+
+          # `Array[T]#flatten` (and `flatten(depth)`). When `T` is a
+          # nested `Array[U]` nominal, one flatten level yields the
+          # joined inner element type — `Array[Array[U]]#flatten` →
+          # `Array[U]`. When `T` is non-nested the result is `Array[T]`
+          # unchanged (Ruby returns a copy with the same element type).
+          # Multi-level nesting is handled conservatively: each level
+          # joins its element types, and a `depth` argument that does
+          # not fully resolve the nesting still produces a sound
+          # superset. Declines on an `Array` with no type argument
+          # (the RBS `Array[untyped]` answer is already as precise as
+          # we can be) and on a non-static depth argument.
+          def array_nominal_flatten(nominal, args)
+            element = nominal.type_args&.first
+            return nil if element.nil?
+
+            depth = tuple_flatten_depth(args)
+            return nil if depth == :decline
+
+            flattened = flatten_nominal_element(element, depth)
+            Type::Combinator.nominal_of("Array", type_args: [flattened])
+          end
+
+          # 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).
+          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)
+          end
+
+          def array_nominal?(type)
+            type.is_a?(Type::Nominal) && type.class_name == "Array" && !type.type_args.nil? &&
+              !type.type_args.empty?
+          end
+
           # Arg-type-driven String binary projections for any String-typed
           # receiver (including Nominal, Refined, and Difference fallbacks).
           # Called before the no-arg size guard so binary operators are seen.
@@ -875,6 +969,50 @@ module Rigor
             constant_index(tuple, args) { |elements, value| elements.index { |e| e.value == value } }
           end
 
+          # `tuple.flatten` / `tuple.flatten(depth)` — recursively
+          # flattens nested Tuple elements into a single Tuple. With
+          # no argument the flatten is unbounded (matching Ruby's
+          # `Array#flatten`); a `Constant[Integer]` depth bounds it.
+          # Non-Tuple elements (scalars, `Array[T]` nominals, …) pass
+          # through unchanged at their level. A non-static depth
+          # argument (or a non-Integer one) declines so RBS answers.
+          def tuple_flatten(tuple, _method_name, args)
+            depth = tuple_flatten_depth(args)
+            return nil if depth == :decline
+
+            Type::Combinator.tuple_of(*flatten_elements(tuple.elements, depth))
+          end
+
+          # Returns the requested flatten depth: `-1` for the no-arg
+          # (unbounded) form, the Integer for a `Constant[Integer]`
+          # argument, or `:decline` for any non-static / wrong-arity
+          # argument shape.
+          def tuple_flatten_depth(args)
+            return -1 if args.empty?
+            return :decline unless args.size == 1
+
+            arg = args.first
+            return arg.value if arg.is_a?(Type::Constant) && arg.value.is_a?(Integer)
+
+            :decline
+          end
+
+          # Flattens a list of element types to `depth` levels.
+          # `depth < 0` means unbounded. A Tuple element is spliced
+          # in (recursing with `depth - 1`); everything else passes
+          # through at this level.
+          def flatten_elements(elements, depth)
+            return elements if depth.zero?
+
+            elements.flat_map do |element|
+              if element.is_a?(Type::Tuple)
+                flatten_elements(element.elements, depth - 1)
+              else
+                [element]
+              end
+            end
+          end
+
           # `rindex(obj)` → the LAST matching index, same decidability gate.
           def tuple_rindex(tuple, _method_name, args)
             constant_index(tuple, args) { |elements, value| elements.rindex { |e| e.value == value } }

data/lib/rigor/inference/method_dispatcher.rb

@@ -14,7 +14,9 @@ require_relative "method_dispatcher/shape_dispatch"
 require_relative "method_dispatcher/data_folding"
 require_relative "method_dispatcher/rbs_dispatch"
 require_relative "method_dispatcher/iterator_dispatch"
+require_relative "method_dispatcher/reduce_folding"
 require_relative "method_dispatcher/block_folding"
+require_relative "method_dispatcher/array_to_h_folding"
 require_relative "method_dispatcher/file_folding"
 require_relative "method_dispatcher/shellwords_folding"
 require_relative "method_dispatcher/math_folding"
@@ -274,7 +276,14 @@ module Rigor
         class_name, kind = discovered_method_lookup(receiver_type)
         return nil if class_name.nil?
         return nil unless scope.discovered_method?(class_name, method_name, kind)
+        # Decline when a re-typable body is recorded for the method, so the
+        # downstream `ExpressionTyper` inference tier can fold a precise
+        # return instead of collapsing to `Dynamic[top]` here — instance
+        # bodies via `user_def_for`, singleton bodies (`def self.x` /
+        # `module_function`) via `singleton_def_for` (module-singleton
+        # call resolution, ADR-57 follow-up).
         return nil if kind == :instance && scope.user_def_for(class_name, method_name)
+        return nil if kind == :singleton && scope.singleton_def_for(class_name, method_name)
 
         Type::Combinator.untyped
       end
@@ -792,7 +801,7 @@ module Rigor
       private_constant :STDLIB_SINGLETON_FOLDERS
 
       PRECISE_TIERS_TAIL = Ractor.make_shareable([
-        KernelDispatch, MethodFolding, BlockFolding
+        KernelDispatch, MethodFolding, ReduceFolding, ArrayToHFolding, BlockFolding
       ].freeze)
       private_constant :PRECISE_TIERS_TAIL
 
@@ -952,18 +961,53 @@ module Rigor
         set_lift = set_new_lift(receiver_type.class_name, arg_types)
         return set_lift if set_lift
 
+        hash_lift = hash_new_lift(receiver_type.class_name, arg_types)
+        return hash_lift if hash_lift
+
         regexp_lift = regexp_new_lift(receiver_type.class_name, arg_types)
         return regexp_lift if regexp_lift
 
         date_lift = date_new_lift(receiver_type.class_name, arg_types)
         return date_lift if date_lift
 
+        struct_new_lift = struct_new_lift(receiver_type.class_name, arg_types)
+        return struct_new_lift if struct_new_lift
+
         class_new_lift = class_new_lift(receiver_type.class_name, arg_types)
         return class_new_lift if class_new_lift
 
         Type::Combinator.nominal_of(receiver_type.class_name)
       end
 
+      # `Struct.new(:a, :b)` synthesises an anonymous Struct *subclass*
+      # (a class object), not a Struct *instance* — so the chained
+      # idiom `Struct.new(:a, :b).new(1, 2)` must resolve `.new` again
+      # on a class-like carrier. The constant-bound form
+      # (`S = Struct.new(:a); S.new(1)`) already records `Singleton[S]`
+      # via `ScopeIndexer#record_meta_new_constant?`; this lift gives
+      # the *chained* (anonymous) position the same class-like carrier
+      # so the trailing `.new` dispatches instead of firing a spurious
+      # `undefined method 'new' for Struct`.
+      #
+      # The disambiguation mirrors `ScopeIndexer#struct_new_call?`: a
+      # call whose positionals are all `Constant<Symbol>` literals is a
+      # member-list class definition → `Singleton[Struct]`. The
+      # following `AnonStruct.new(1, 2)` carries non-symbol args, so it
+      # falls through this gate to `Nominal[Struct]` (a fresh instance)
+      # via the `meta_new` tail. ADR-48 deferred full Struct *value*
+      # folding (member-reader precision) on mutability grounds; this is
+      # the narrower `.new`-dispatch-only fix and contributes no member
+      # layout, so `instance.a` stays at its RBS/Dynamic type.
+      def struct_new_lift(class_name, arg_types)
+        return nil unless class_name == "Struct"
+
+        positional = arg_types.grep_v(Type::HashShape)
+        return nil if positional.empty?
+        return nil unless positional.all? { |t| t.is_a?(Type::Constant) && t.value.is_a?(Symbol) }
+
+        Type::Combinator.singleton_of("Struct")
+      end
+
       # `Class.new` and `Class.new(Parent)` create a brand-new
       # anonymous class. Statically that class is representable as
       # the parent's singleton type — its singleton-method surface
@@ -1050,6 +1094,33 @@ module Rigor
         type
       end
 
+      # `Hash.new(default)` — lifts the default value's type into the
+      # Hash's value parameter so a subsequent `h[k]` read surfaces the
+      # default type rather than `Dynamic[top]`. The common counter
+      # idiom `h = Hash.new(0); h[k] += 1` then types the read as
+      # `Integer`. The key parameter is left `untyped` (the default
+      # carrier imposes no key constraint), so reads of any key resolve
+      # through the value parameter. A value-pinned `Constant` default
+      # (`0`) is widened to its nominal (`Integer`): the hash's values
+      # mutate over its lifetime, so pinning the parameter to the
+      # literal would be unsound for the aggregate.
+      #
+      # Only the single-argument default form folds. The zero-arg
+      # (`Hash.new`) and the block form (`Hash.new { |h, k| … }`) keep
+      # the bare `Nominal[Hash]` answer — the block's value type is not
+      # available at this `:new` dispatch site, and conservatively
+      # leaving the read as today's behaviour is precision-additive.
+      def hash_new_lift(class_name, arg_types)
+        return nil unless class_name == "Hash"
+        return nil unless arg_types.size == 1
+
+        default = arg_types.first
+        return nil if default.nil?
+
+        value = Type::Combinator.widen_value_pinned(default)
+        Type::Combinator.nominal_of("Hash", type_args: [Type::Combinator.untyped, value])
+      end
+
       # `Range.new(b, e)` / `Range.new(b, e, excl)` — folds to
       # `Constant[Range]` when both endpoints are `Constant[Integer]`
       # or both are `Constant[String]`, and the optional third argument

data/lib/rigor/inference/method_parameter_binder.rb

@@ -32,6 +32,35 @@ module Rigor
     # `#singleton_method`.
     #
     # See docs/internal-spec/inference-engine.md for the binding contract.
+    # Leaf-name extraction for a destructured positional parameter
+    # (`Prism::MultiTargetNode`). Stateless; lifted out of
+    # {MethodParameterBinder} so the binder's class length stays in
+    # budget.
+    module Destructure
+      module_function
+
+      # Collect every leaf local name a `MultiTargetNode` binds,
+      # recursing through nested destructures (`((a, b), c)`) and the
+      # splat slot (`(a, *rest)`). Targets without a `#name` (an
+      # index/call write target, vanishingly rare in a parameter
+      # position) are skipped — there is no local to bind.
+      def target_names(multi_target)
+        entries = multi_target.lefts + [multi_target.rest, *multi_target.rights].compact
+        entries.flat_map { |entry| names_for_entry(entry) }
+      end
+
+      def names_for_entry(entry)
+        # A splat sub-target (`*rest` inside the destructure) wraps its
+        # real target in a `SplatNode#expression`; unwrap it.
+        entry = entry.expression if entry.is_a?(Prism::SplatNode) && entry.expression
+        return [] if entry.nil?
+        return target_names(entry) if entry.is_a?(Prism::MultiTargetNode)
+        return [entry.name] if entry.respond_to?(:name) && entry.name
+
+        []
+      end
+    end
+
     class MethodParameterBinder
       # @param environment [Rigor::Environment]
       # @param class_path [String, nil] the qualified name of the class
@@ -112,14 +141,39 @@ module Rigor
 
       def positional_slots(params_node)
         slots = []
-        params_node.requireds.each_with_index { |p, i| slots << ParamSlot.new(:required_positional, p.name, i) }
+        params_node.requireds.each_with_index do |p, i|
+          append_positional_slot(slots, :required_positional, p, i)
+        end
         params_node.optionals.each_with_index { |p, i| slots << ParamSlot.new(:optional_positional, p.name, i) }
         rest = params_node.rest
         slots << ParamSlot.new(:rest_positional, rest.name, nil) if rest.respond_to?(:name) && rest&.name
-        params_node.posts.each_with_index { |p, i| slots << ParamSlot.new(:trailing_positional, p.name, i) }
+        params_node.posts.each_with_index do |p, i|
+          append_positional_slot(slots, :trailing_positional, p, i)
+        end
         slots
       end
 
+      # A destructured positional parameter — `def f((a, b))` — is a
+      # `Prism::MultiTargetNode` in the `requireds`/`posts` list, not a
+      # `RequiredParameterNode`, so it has no `#name`. Bind each leaf
+      # sub-target local to `Dynamic[Top]` (a `:destructured_positional`
+      # slot with no RBS index) instead of crashing on a blind `.name`.
+      # Binding the names at all is what matters: it keeps the
+      # destructured locals present in the entry scope so the body's
+      # reads of them don't fall through to undefined-local noise. The
+      # element types are not cheaply available from the parameter list
+      # alone (no RBS function param maps onto a destructured slot), so
+      # `Dynamic[Top]` is the sound default.
+      def append_positional_slot(slots, kind, param, index)
+        if param.is_a?(Prism::MultiTargetNode)
+          Destructure.target_names(param).each do |name|
+            slots << ParamSlot.new(:destructured_positional, name, nil)
+          end
+        else
+          slots << ParamSlot.new(kind, param.name, index)
+        end
+      end
+
       def keyword_slots(params_node)
         params_node.keywords.filter_map do |kw|
           case kw

data/lib/rigor/inference/multi_target_binder.rb

@@ -100,19 +100,62 @@ module Rigor
 
         def decompose_tuple(tuple, front_count, back_count, rest_present:)
           elements = tuple.elements
-          fronts = Array.new(front_count) { |i| elements[i] || Type::Combinator.constant_of(nil) }
+          fronts = Array.new(front_count) { |i| slot_type(elements, i) }
           if rest_present
             middle_end = [elements.size - back_count, front_count].max
             middle = elements[front_count...middle_end] || []
             rest_type = Type::Combinator.tuple_of(*middle)
-            backs = Array.new(back_count) { |i| elements[middle_end + i] || Type::Combinator.constant_of(nil) }
+            backs = Array.new(back_count) { |i| slot_type(elements, middle_end + i) }
           else
             rest_type = nil
-            backs = Array.new(back_count) { |i| elements[front_count + i] || Type::Combinator.constant_of(nil) }
+            backs = Array.new(back_count) { |i| slot_type(elements, front_count + i) }
           end
           [fronts, rest_type, backs]
         end
 
+        # The per-slot type for index `i` of a tuple decomposition, FP-safely
+        # softened: a missing slot is `nil` (the runtime value of an
+        # over-destructured positional), and a PRESENT but nil-bearing slot
+        # (`X | nil`) is softened to its non-`nil` part — for a heterogeneous
+        # `Tuple` whose optional slot was made optional by flow.
+        #
+        # Rationale (ADR-57 slice 3 work-item 2): a destructure of a tuple
+        # element that flow typed as optional is almost always guarded by a
+        # CORRELATED invariant the flow engine cannot prove. The canonical case
+        # is haml's `parse_tag`, which returns `[..., last_line || @line.index
+        # + 1]` — a 9-tuple whose `last_line` slot widens to `Dynamic[top]?`
+        # through a loop-nested destructure; at the call site `..., last_line =
+        # parse_tag(text); raise(..., last_line - 1) if parse && value.empty?`
+        # the `last_line` is nil ONLY when an earlier element is too, and the
+        # guard short-circuits — but that correlation lives across slots, so
+        # per-slot flow sees `last_line` as nil-able and `last_line - 1` fires a
+        # spurious `possible nil receiver`. Manufacturing a `T?` for every
+        # destructured slot frightens working code; FP discipline (the program
+        # works) outranks the worst-case per-slot reading, so we drop the `nil`
+        # from a destructured slot and keep the non-`nil` constituent (a bare
+        # `nil` slot stays `nil` — there is nothing to soften). A pure non-
+        # optional element keeps its precise type unchanged.
+        def slot_type(elements, index)
+          element = elements[index]
+          return Type::Combinator.constant_of(nil) if element.nil?
+
+          soften_optional_slot(element)
+        end
+
+        def soften_optional_slot(element)
+          return element unless element.is_a?(Type::Union)
+          return element unless element.members.any? { |m| nil_literal?(m) }
+
+          non_nil = element.members.reject { |m| nil_literal?(m) }
+          return element if non_nil.empty? # a bare `nil` slot: nothing to soften
+
+          Type::Combinator.union(*non_nil)
+        end
+
+        def nil_literal?(member)
+          member.is_a?(Type::Constant) && member.value.nil?
+        end
+
         def decompose_default(front_count, back_count, rest_present:)
           [
             Array.new(front_count) { Type::Combinator.untyped },

data/lib/rigor/inference/mutation_widening.rb

@@ -280,6 +280,148 @@ module Rigor
         carriers = kinds.map { |name| Type::Combinator.nominal_of(name) }
         carriers.size == 1 ? carriers.first : Type::Combinator.union(*carriers)
       end
+
+      # ----------------------------------------------------------------
+      # ADR-56 slice C — receiver-content element-type JOIN.
+      #
+      # `widen_after_block` above forgets a literal-shape carrier's arity
+      # when a captured local is content-mutated inside a block, but it
+      # keeps only the SEED's element types — an unsound under-
+      # approximation for a non-empty seed (`out = [0]; arr.each { |x|
+      # out << x }` types `Array[0]` while the runtime array is
+      # `[0, 1, 2, 3]`). Slice C joins the appended/stored element (and
+      # key/value) types INTO the continuation collection's parameter, so
+      # the result is `Array[0 | Integer]` rather than `Array[0]`.
+      #
+      # Array content-mutators that append/store ELEMENTS. The appended
+      # element type is the call's argument type(s); `[]=`'s value is its
+      # LAST argument (the keys precede it). Subset of `ARRAY_MUTATORS`:
+      # only the element-INTRODUCING methods (removers / reorderers add no
+      # new element evidence and are already covered by the arity-forget).
+      ARRAY_CONTENT_ADDERS = %i[
+        << push append prepend unshift concat insert []= fill replace
+      ].to_set.freeze
+
+      # Hash content-mutators that store a key→value pair. For `[]=` /
+      # `store` the key is the first argument and the value the last.
+      HASH_CONTENT_ADDERS = %i[[]= store].to_set.freeze
+
+      # String content-mutators that append to the buffer. String carries
+      # no element parameter, so these contribute nothing to a join — they
+      # are listed so the orchestrator recognises them as content mutators
+      # (the binding already widens to `String` via normal typing); the
+      # join helpers below short-circuit on a non-collection pre-state.
+      STRING_CONTENT_ADDERS = %i[<< concat prepend insert replace].to_set.freeze
+
+      # Every method name that mutates a captured local's CONTENT — the
+      # union the orchestrator scans the block body for.
+      CONTENT_ADDERS = (ARRAY_CONTENT_ADDERS | HASH_CONTENT_ADDERS | STRING_CONTENT_ADDERS).freeze
+
+      # The element types a single content-mutator call introduces into an
+      # Array, given the per-argument types (already typed in the block
+      # body scope). `concat`/`replace` take collection arguments, so their
+      # element evidence is the arguments' OWN element types unioned; the
+      # rest append the argument values directly. Returns `[]` when no
+      # element evidence (e.g. a `<<` with no resolvable arg).
+      def array_added_elements(method_name, arg_types)
+        return [] if arg_types.empty?
+
+        case method_name
+        when :concat, :replace
+          arg_types.flat_map { |t| collection_element_types(t) }
+        when :insert
+          # `insert(index, *objs)` — first arg is the position.
+          arg_types.drop(1)
+        when :[]=
+          # `arr[i] = v` / `arr[i, n] = v` — value is the last argument.
+          [arg_types.last]
+        when :fill
+          # `fill(value)` — only the no-block single-value form adds a
+          # concrete element; block / range forms are conservatively
+          # ignored (the arity-forget already widened the binding).
+          arg_types.size == 1 ? arg_types : []
+        else # << push append prepend unshift
+          arg_types
+        end
+      end
+
+      # Builds the continuation Array type from the pre-state binding and
+      # the appended element types. The floor is `Array[Dynamic[top]]`
+      # (the sound empty-seed behaviour) when there is no element evidence
+      # at all.
+      def join_array_content(pre_state, added_elements)
+        seed_elements = collection_element_types(pre_state)
+        added = added_elements.compact
+        # The empty-seed floor element is `Dynamic[top]` (no element
+        # evidence). When real appended evidence exists that floor carries
+        # nothing, so drop it — an empty accumulator built by `out << x*2`
+        # reads `Array[Integer]`, not `Array[Integer | Dynamic[top]]`.
+        seed_elements = drop_dynamic(seed_elements) unless added.empty?
+        elements = seed_elements + added
+        return Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.untyped]) if elements.empty?
+
+        Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.union(*elements)])
+      end
+
+      # Builds the continuation Hash type from the pre-state binding and a
+      # list of `[key_type, value_type]` pairs stored by `[]=` / `store`.
+      def join_hash_content(pre_state, added_pairs)
+        seed_keys, seed_values = hash_shape_key_values(pre_state)
+        added_keys = added_pairs.map(&:first).compact
+        added_values = added_pairs.map(&:last).compact
+        seed_keys = drop_dynamic(seed_keys) unless added_keys.empty?
+        seed_values = drop_dynamic(seed_values) unless added_values.empty?
+        keys = seed_keys + added_keys
+        values = seed_values + added_values
+        key_t = keys.empty? ? Type::Combinator.untyped : Type::Combinator.union(*keys)
+        value_t = values.empty? ? Type::Combinator.untyped : Type::Combinator.union(*values)
+        Type::Combinator.nominal_of("Hash", type_args: [key_t, value_t])
+      end
+
+      # Drops `Dynamic` (incl. `untyped`) constituents from a type list.
+      def drop_dynamic(types)
+        types.grep_v(Type::Dynamic)
+      end
+
+      # Element types carried by a collection binding, regardless of which
+      # carrier holds them: a `Tuple` lists them, a `Nominal[Array, [E]]`
+      # has one element param, a bare `Array` / anything else yields none.
+      def collection_element_types(type)
+        case type
+        when Type::Tuple
+          type.elements
+        when Type::Nominal
+          type.class_name == "Array" ? type.type_args : []
+        when Type::Union
+          # A loop's single-pass join can union the widened collection with
+          # its un-widened literal seed (`Array[0] | [0]`); pull element
+          # evidence from every Array-ish member.
+          type.members.flat_map { |m| collection_element_types(m) }
+        else
+          []
+        end
+      end
+
+      # `[keys, values]` evidence from a Hash-ish pre-state binding —
+      # a `HashShape` (literal pairs) or a `Nominal[Hash, [K, V]]`.
+      def hash_shape_key_values(type)
+        case type
+        when Type::HashShape
+          return [[], []] if type.pairs.empty?
+
+          [[key_union_for(type.pairs.keys)], type.pairs.values]
+        when Type::Nominal
+          type.class_name == "Hash" && type.type_args.size == 2 ? [[type.type_args[0]], [type.type_args[1]]] : [[], []]
+        when Type::Union
+          type.members.each_with_object([[], []]) do |m, (ks, vs)|
+            mk, mv = hash_shape_key_values(m)
+            ks.concat(mk)
+            vs.concat(mv)
+          end
+        else
+          [[], []]
+        end
+      end
     end
   end
 end