rigortype 0.1.17 → 0.1.19

data/lib/rigor/inference/method_dispatcher.rb

@@ -6,6 +6,7 @@ require_relative "../flow_contribution"
 require_relative "../flow_contribution/merger"
 require_relative "../builtins/hkt_builtins"
 require_relative "../builtins/static_return_refinements"
+require_relative "flow_tracer"
 require_relative "method_dispatcher/call_context"
 require_relative "method_dispatcher/constant_folding"
 require_relative "method_dispatcher/literal_string_folding"
@@ -13,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"
@@ -73,9 +76,28 @@ module Rigor
       # @param environment [Rigor::Environment, nil] required for
       #   RBS-backed dispatch; when nil only constant folding can fire.
       # @return [Rigor::Type, nil] inferred result type, or `nil` for "no rule".
-      def dispatch(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def dispatch(receiver_type:, method_name:, arg_types:,
                    block_type: nil, environment: nil,
                    call_node: nil, scope: nil)
+        result = resolve(
+          receiver_type: receiver_type, method_name: method_name, arg_types: arg_types,
+          block_type: block_type, environment: environment,
+          call_node: call_node, scope: scope
+        )
+        # `rigor trace` — record the dispatch outcome (resolved type, or
+        # the fail-soft `nil` the caller widens to `Dynamic[Top]`).
+        if FlowTracer.active?
+          FlowTracer.dispatch(
+            receiver: receiver_type, method_name: method_name, args: arg_types,
+            result: result, location: call_node&.location
+          )
+        end
+        result
+      end
+
+      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+                  block_type: nil, environment: nil,
+                  call_node: nil, scope: nil)
         return nil if receiver_type.nil?
 
         # Build the call context once and thread it — unchanged —
@@ -217,7 +239,7 @@ module Rigor
         # introspection (`attr_reader`, `private`, ...) on
         # user classes without requiring the user to author
         # their own RBS.
-        try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type, call_node)
+        try_user_class_fallback(receiver_type, environment, call_node, context)
       end
 
       # v0.1.3 — discovered-method dispatch tier. `scope` carries
@@ -254,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
@@ -298,12 +327,12 @@ module Rigor
       end
 
       # ADR-2 § "Flow Contribution Bundle" / v0.1.1 Track 2
-      # slice 7. Walks every loaded plugin's
-      # `#flow_contribution_for(call_node:, scope:)` hook,
-      # collects the non-nil `FlowContribution` bundles, merges
-      # them through `FlowContribution::Merger`, and returns
-      # the merged `return_type` slot (or nil when no plugin
-      # contributed a return type).
+      # slice 7; ADR-52 WD3 — consults each loaded plugin's gated
+      # `dynamic_return` rules, wraps the contributed types as
+      # `FlowContribution` bundles, merges them through
+      # `FlowContribution::Merger`, and returns the merged
+      # `return_type` slot (or nil when no plugin contributed a
+      # return type).
       #
       # Plugins whose hook raises have their contribution
       # silently dropped for this call so the dispatch chain
@@ -643,23 +672,15 @@ module Rigor
         Type::Combinator.untyped
       end
 
+      # ADR-52 WD1 — the per-dispatch plugins × owns_receivers ×
+      # `class_ordering` walk moved into the compiled contribution
+      # table: the union is built once per registry (almost always
+      # empty → O(1) false) and per-class verdicts memoise per run.
       def plugin_owns_receiver?(class_name, environment)
         registry = environment&.plugin_registry
         return false if registry.nil? || registry.empty?
 
-        registry.plugins.any? do |plugin|
-          owns = plugin.manifest.owns_receivers # rigor:disable undefined-method
-          owns.any? { |owner| receiver_matches_owner?(class_name, owner, environment) }
-        end
-      end
-
-      def receiver_matches_owner?(class_name, owner, environment)
-        return true if class_name == owner
-
-        ordering = environment.class_ordering(class_name, owner)
-        %i[equal subclass].include?(ordering)
-      rescue StandardError
-        false
+        registry.contribution_index.owns_receiver?(class_name, environment)
       end
 
       def dep_source_class_name(receiver_type)
@@ -668,11 +689,11 @@ module Rigor
         end
       end
 
-      # ADR-37 slice 2 — gathers each plugin's return-type contribution
-      # from BOTH the narrow `dynamic_return` DSL (receiver-gated, wrapped
-      # as a return-only `FlowContribution`) and the legacy
-      # `flow_contribution_for` escape valve, so migrated and unmigrated
-      # plugins compose through the same merger.
+      # ADR-37 slice 2 / ADR-52 WD3 — gathers each plugin's return-type
+      # contribution from the gated `dynamic_return` DSL, wrapped as a
+      # return-only `FlowContribution` for the shared merger. (The legacy
+      # ungated `flow_contribution_for` escape valve was deleted once its
+      # five users migrated.)
       EMPTY_CONTRIBUTIONS = [].freeze
       private_constant :EMPTY_CONTRIBUTIONS
 
@@ -682,31 +703,48 @@ module Rigor
       #
       # 1. Only the plugins that *structurally* implement a per-call path
       #    are visited — `registry.contribution_index.for_method_dispatch`
-      #    is the registry-ordered subset overriding `flow_contribution_for`
-      #    or declaring a `dynamic_return` (GitLab: 2 of 11). Iterating the
-      #    subset in registry order, and gating each path by membership,
-      #    yields the exact same contributions in the same order as
-      #    visiting every plugin would (a skipped plugin's call returns
-      #    nil/[] anyway). The receiver-class ancestry match still happens
-      #    per dispatch inside `dynamic_return_type`.
+      #    is the registry-ordered subset declaring a `dynamic_return`.
+      #    Iterating the subset in registry order, and gating each path by
+      #    membership, yields the exact same contributions in the same
+      #    order as visiting every plugin would (a skipped plugin's call
+      #    returns nil/[] anyway). The receiver-class ancestry match still
+      #    happens per dispatch inside `dynamic_return_type`.
       # 2. Contributions accumulate lazily — allocate only when one
       #    actually appears, and share a frozen empty array otherwise. The
       #    caller treats the result as read-only (`.empty?` / `Merger.merge`).
+      # 3. ADR-52 WD1 — method-name gates compiled at registry build. The
+      #    global gate makes the common "no plugin cares about this call"
+      #    case a single Set probe; the per-plugin gate skips a plugin
+      #    whose `dynamic_return` rules are all `methods:`-gated on other
+      #    names. A pruned consultation could only have returned nil, so
+      #    contribution order and content are unchanged.
       def collect_plugin_contributions(registry, call_node, scope, receiver_type)
         index = registry.contribution_index
         relevant = index.for_method_dispatch
         return EMPTY_CONTRIBUTIONS if relevant.empty?
 
+        # `call_node` is not always a CallNode — the `&:symbol` block
+        # path dispatches with the `Prism::BlockArgumentNode` itself
+        # (`ExpressionTyper#symbol_block_return_type`). A bare `.name`
+        # here raised, and the raise was silently absorbed by
+        # `block_return_type_for`'s rescue, nil-ing the block type and
+        # flipping `select(&:p)`-style calls onto their no-block
+        # Enumerator overloads (caught by the GitLab corpus gate).
+        name = call_node.respond_to?(:name) ? call_node.name : nil
+        return EMPTY_CONTRIBUTIONS unless index.dispatch_candidate?(name)
+
+        collect_gated_contributions(index, relevant, name, call_node, scope, receiver_type)
+      end
+
+      # The post-gate walk, in registry order — the same order the
+      # ungated walk used.
+      def collect_gated_contributions(index, relevant, name, call_node, scope, receiver_type)
         result = nil
         relevant.each do |plugin|
-          if index.flow?(plugin)
-            legacy = plugin.flow_contribution_for(call_node: call_node, scope: scope)
-            (result ||= []) << legacy if legacy.is_a?(FlowContribution)
-          end
-          if index.dynamic?(plugin)
-            dynamic = plugin.dynamic_return_type(call_node: call_node, scope: scope, receiver_type: receiver_type)
-            (result ||= []) << FlowContribution.new(return_type: dynamic) if dynamic
-          end
+          next unless index.dynamic_candidate_for?(plugin, name)
+
+          dynamic = plugin.dynamic_return_type(call_node: call_node, scope: scope, receiver_type: receiver_type)
+          (result ||= []) << FlowContribution.new(return_type: dynamic) if dynamic
         rescue StandardError
           next
         end
@@ -735,13 +773,37 @@ module Rigor
       # filter the common cases first. Adding a precise tier is a
       # one-line append here rather than another link in a hand-written
       # `||` ladder.
-      PRECISE_TIERS = Ractor.make_shareable([
-        ConstantFolding, LiteralStringFolding, ShapeDispatch,
-        FileFolding, ShellwordsFolding, MathFolding, TimeFolding,
-        RegexpFolding, CGIFolding, URIFolding, SetFolding,
-        KernelDispatch, MethodFolding, BlockFolding
+      PRECISE_TIERS_HEAD = Ractor.make_shareable([
+        ConstantFolding, LiteralStringFolding, ShapeDispatch
       ].freeze)
-      private_constant :PRECISE_TIERS
+      private_constant :PRECISE_TIERS_HEAD
+
+      # ADR-53 re-review follow-up (gate-by-held-key applied to the
+      # built-in tiers): the eight stdlib singleton folders are mutually
+      # exclusive — each fires only on `Singleton[<its class>]`, the
+      # first check in every `try_dispatch` — so at most one can match a
+      # given receiver and their relative trial order was never
+      # observable. Compiling them into a class-name table turns eight
+      # no-op trials per call into one Hash read, skipped entirely when
+      # the receiver is not a `Singleton` (the overwhelmingly common
+      # case). The table sits where the eight sat in the old flat list:
+      # after ShapeDispatch, before KernelDispatch.
+      STDLIB_SINGLETON_FOLDERS = Ractor.make_shareable({
+        "File" => FileFolding,
+        "Shellwords" => ShellwordsFolding,
+        "Math" => MathFolding,
+        "Time" => TimeFolding,
+        "Regexp" => RegexpFolding,
+        "CGI" => CGIFolding,
+        "URI" => URIFolding,
+        "Set" => SetFolding
+      }.freeze)
+      private_constant :STDLIB_SINGLETON_FOLDERS
+
+      PRECISE_TIERS_TAIL = Ractor.make_shareable([
+        KernelDispatch, MethodFolding, ReduceFolding, ArrayToHFolding, BlockFolding
+      ].freeze)
+      private_constant :PRECISE_TIERS_TAIL
 
       def dispatch_precise_tiers(context)
         # ADR-48 — Data value folding runs ahead of meta-introspection:
@@ -756,14 +818,25 @@ module Rigor
         meta_result = try_meta_introspection(context.receiver, context.method_name, context.args)
         return meta_result if meta_result
 
-        PRECISE_TIERS.each do |tier|
+        PRECISE_TIERS_HEAD.each do |tier|
+          result = tier.try_dispatch(context)
+          return result if result
+        end
+
+        receiver = context.receiver
+        if receiver.is_a?(Type::Singleton) && (folder = STDLIB_SINGLETON_FOLDERS[receiver.class_name])
+          result = folder.try_dispatch(context)
+          return result if result
+        end
+
+        PRECISE_TIERS_TAIL.each do |tier|
           result = tier.try_dispatch(context)
           return result if result
         end
         nil
       end
 
-      def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type, call_node = nil)
+      def try_user_class_fallback(receiver_type, environment, call_node, context)
         return nil if environment.nil?
 
         fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
@@ -788,14 +861,11 @@ module Rigor
         # self / `self.`-receiver calls (`puts`, `raise`, `require`)
         # keep resolving — those are the fallback's intended targets.
         RbsDispatch.try_dispatch(
-          CallContext.build(
+          context.with(
             receiver: fallback_receiver,
-            method_name: method_name,
-            args: arg_types,
-            environment: environment,
-            block_type: block_type,
             self_type_override: receiver_type,
-            public_only: explicit_non_self_receiver?(call_node)
+            public_only: explicit_non_self_receiver?(call_node),
+            call_node: nil, scope: nil
           )
         )
       end
@@ -891,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
@@ -989,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