rigortype 0.2.8 → 0.3.0

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

@@ -4,6 +4,7 @@ require_relative "../../reflection"
 require_relative "../../type"
 require_relative "../../rbs_extended"
 require_relative "../rbs_type_translator"
+require_relative "../void_origin"
 require_relative "overload_selector"
 
 module Rigor
@@ -96,7 +97,8 @@ module Rigor
             block_type: context.block_type,
             self_type_override: context.self_type_override,
             public_only: context.public_only,
-            scope: context.scope
+            scope: context.scope,
+            call_node: context.call_node
           )
         end
 
@@ -135,23 +137,23 @@ module Rigor
           private
 
           def dispatch_for(receiver:, method_name:, args:, environment:, block_type:, self_type_override: nil, # rubocop:disable Metrics/ParameterLists
-                           public_only: false, scope: nil)
+                           public_only: false, scope: nil, call_node: nil)
             args ||= []
             case receiver
             when Type::Union
               dispatch_union(receiver, method_name, args, environment, block_type, self_type_override,
-                             public_only: public_only, scope: scope)
+                             public_only: public_only, scope: scope, call_node: call_node)
             else
               dispatch_one(receiver, method_name, args, environment, block_type, self_type_override,
-                           public_only: public_only, scope: scope)
+                           public_only: public_only, scope: scope, call_node: call_node)
             end
           end
 
           def dispatch_union(receiver, method_name, args, environment, block_type, self_type_override = nil, # rubocop:disable Metrics/ParameterLists
-                             public_only: false, scope: nil)
+                             public_only: false, scope: nil, call_node: nil)
             results = receiver.members.map do |member|
               dispatch_one(member, method_name, args, environment, block_type, self_type_override,
-                           public_only: public_only, scope: scope)
+                           public_only: public_only, scope: scope, call_node: call_node)
             end
             return nil if results.any?(&:nil?)
 
@@ -159,7 +161,7 @@ module Rigor
           end
 
           def dispatch_one(receiver, method_name, args, environment, block_type, self_type_override = nil, # rubocop:disable Metrics/ParameterLists
-                           public_only: false, scope: nil)
+                           public_only: false, scope: nil, call_node: nil)
             descriptor = receiver_descriptor(receiver)
             return nil unless descriptor
 
@@ -173,11 +175,14 @@ module Rigor
               method_definition,
               class_name: class_name,
               kind: kind,
+              method_name: method_name,
               args: args,
               type_vars: type_vars,
               block_type: block_type,
               environment: environment,
-              self_type_override: self_type_override
+              self_type_override: self_type_override,
+              scope: scope,
+              call_node: call_node
             )
           rescue StandardError
             # Defensive: if RBS' definition builder raises on a broken hierarchy (e.g., partially loaded
@@ -318,7 +323,8 @@ module Rigor
 
           # rubocop:disable Metrics/ParameterLists
           def translate_return_type(method_definition, class_name:, kind:, args:, type_vars:, block_type:,
-                                    environment: nil, self_type_override: nil)
+                                    method_name: nil, environment: nil, self_type_override: nil,
+                                    scope: nil, call_node: nil)
             # rubocop:enable Metrics/ParameterLists
             # Slice 4b-3 (ADR-7 § "Slice 4-A/4-B") — read the return-type override through the merger so
             # future plugin / `:rbs_extended` bundles that also assert a `return_type` slot at this call
@@ -348,6 +354,15 @@ module Rigor
             )
             return nil unless method_type
 
+            # ADR-100 WD2/WD3 — the return-typing tier is where `void → top` widens, so it is the one place
+            # that still knows the RBS return was an author-declared `-> void` before the translator erases
+            # it to a plain `top`. Record the recovery on the scope's `void_origins` side-table, keyed by the
+            # call node, so the `static.value-use.void` check rule can fire when this `top` is used in value
+            # context. Recording is gated on `scope` && `call_node` being present, which naturally scopes it
+            # to the *direct*-RBS dispatch (the receiver's own resolvable class): the user-class / Object
+            # ancestor fallback nils both out (WD4 defers that, murkier, surface).
+            record_void_recovery(method_type, scope, call_node, [class_name, method_name, kind])
+
             full_type_vars = compose_block_type_vars(method_type, type_vars, block_type)
 
             RbsTypeTranslator.translate(
@@ -358,6 +373,24 @@ module Rigor
             )
           end
 
+          # Record the `void → top` recovery when the selected overload declares `-> void` and both `scope` and
+          # `call_node` are present (the direct-dispatch path). `void_site` is the `[class_name, method_name,
+          # kind]` triple the {VoidOrigin} carries.
+          def record_void_recovery(method_type, scope, call_node, void_site)
+            return unless scope && call_node && void_return?(method_type)
+
+            class_name, method_name, kind = void_site
+            scope.record_void_origin(
+              call_node,
+              VoidOrigin.new(class_name: class_name, method_name: method_name, kind: kind)
+            )
+          end
+
+          def void_return?(method_type)
+            fun = method_type.type
+            fun.respond_to?(:return_type) && fun.return_type.is_a?(RBS::Types::Bases::Void)
+          end
+
           # ADR-7 § "Slice 4-A/4-B" — folds the `RBS::Extended` `return:` directive (and any other
           # `return_type`-bearing contribution future slices add at this call site) through the merger
           # before consuming. Returns the merged return type or nil when no contribution overrides the

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

@@ -41,8 +41,13 @@ module Rigor
             end
           end
 
+          # `RBS::Types::UntypedFunction` (a `(?)` method type, e.g. core's `Proc#call`) declares no
+          # parameters and exposes none of the per-arity accessors. It has no param classes to compare
+          # against the receiver, so it carries no affinity either way.
           def overload_param_classes_in_ancestry?(method_type, self_class_name, environment)
             fun = method_type.type
+            return false unless fun.respond_to?(:required_positionals)
+
             params = fun.required_positionals + fun.optional_positionals + fun.trailing_positionals
             return false if params.empty?
 

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

@@ -27,13 +27,14 @@ module Rigor
       #   the chain collapses to `Constant[nil]` so the carrier surfaces through downstream narrowing. A
       #   non-shape intermediate falls through to the projection answer.
       # - HashShape#`size`/`length`: no-arg.
-      # - HashShape#`[]`, HashShape#`fetch`, HashShape#`dig` with a single `Constant[Symbol|String]`
-      #   argument matching one of the declared keys. `[]` and `dig` resolve missing keys to
+      # - HashShape#`[]`, HashShape#`fetch`, HashShape#`dig` with a single `Constant` scalar-key
+      #   argument (Symbol / String / Integer / Float / true / false / nil) matching one of the declared
+      #   keys. `[]` and `dig` resolve missing keys to
       #   `Constant[nil]`; `fetch` (no default, no block) falls through on a miss because Ruby would raise
       #   `KeyError` and the analyzer prefers the conservative projection answer.
       # - HashShape#`dig` with multi-arg chains (Slice 5 phase 2 sub-phase 2). Same chaining semantics as
       #   Tuple#`dig`.
-      # - HashShape#`values_at` with a list of `Constant[Symbol|String]` arguments (Slice 5 phase 2
+      # - HashShape#`values_at` with a list of `Constant` scalar-key arguments (Slice 5 phase 2
       #   sub-phase 2). The result is a `Tuple` whose elements are the per-key values (`Constant[nil]` for
       #   missing keys, mirroring Ruby's runtime behaviour).
       #
@@ -244,6 +245,14 @@ module Rigor
             carrier
           end
 
+          # True when `key` is a value the `HashShape` carrier can hold as a key (the value-pinned scalar
+          # set — Symbol, String, Integer, Float, true, false, nil). Key identity in every handler below
+          # is Ruby's own `eql?` via the shape's native `pairs` Hash, so `1` and `1.0` are distinct keys
+          # while `1.0` and `1.00` collide — exactly the runtime's `Hash` semantics.
+          def static_shape_key?(key)
+            Type::HashShape::ALLOWED_KEY_CLASSES.any? { |klass| key.is_a?(klass) }
+          end
+
           def dispatch_nominal_size(nominal, method_name, args)
             projection = nominal_projection(nominal, method_name, args)
             return projection if projection
@@ -424,7 +433,7 @@ module Rigor
             base = difference.base
             return nil unless base.is_a?(Type::Nominal)
 
-            if removes_empty_witness?(difference)
+            if difference.removes_empty_witness?
               precise = empty_removal_projection(difference, method_name, args)
               return precise if precise
             end
@@ -432,23 +441,6 @@ module Rigor
             dispatch_nominal_size(base, method_name, args)
           end
 
-          EMPTY_WITNESS_PREDICATES = {
-            "String" => ->(removed) { removed.is_a?(Type::Constant) && removed.value == "" },
-            "Integer" => lambda { |removed|
-              removed.is_a?(Type::Constant) && removed.value.is_a?(Integer) && removed.value.zero?
-            },
-            "Array" => ->(removed) { removed.is_a?(Type::Tuple) && removed.elements.empty? },
-            "Hash" => ->(removed) { removed.is_a?(Type::HashShape) && removed.pairs.empty? }
-          }.freeze
-          private_constant :EMPTY_WITNESS_PREDICATES
-
-          def removes_empty_witness?(difference)
-            return false unless difference.base.is_a?(Type::Nominal)
-
-            predicate = EMPTY_WITNESS_PREDICATES[difference.base.class_name]
-            !!(predicate && predicate.call(difference.removed))
-          end
-
           # Methods on a non-empty String that preserve non-emptiness (they transform characters but never
           # reduce the string to "").
           NON_EMPTY_STRING_PRESERVING_UNARY = Set[:upcase, :downcase, :capitalize, :swapcase, :reverse].freeze
@@ -1308,7 +1300,7 @@ module Rigor
               return nil unless arg.is_a?(Type::Constant)
 
               key = arg.value
-              return nil unless key.is_a?(Symbol) || key.is_a?(String)
+              return nil unless static_shape_key?(key)
               return nil unless shape.pairs.key?(key)
 
               values << shape.pairs[key]
@@ -1327,7 +1319,7 @@ module Rigor
             return nil unless arg.is_a?(Type::Constant)
 
             key = arg.value
-            return nil unless key.is_a?(Symbol) || key.is_a?(String)
+            return nil unless static_shape_key?(key)
             return Type::Combinator.constant_of(nil) unless shape.pairs.key?(key)
 
             Type::Combinator.tuple_of(Type::Combinator.constant_of(key), shape.pairs[key])
@@ -1436,7 +1428,7 @@ module Rigor
           end
 
           # `shape.has_key?(k)` / `key?(k)` / `member?(k)` / `include?(k)` — folds to `Constant[true/false]`
-          # when the argument is a `Constant[Symbol|String]` and the shape is closed with no optional
+          # when the argument is a `Constant` scalar key and the shape is closed with no optional
           # keys.
           def hash_has_key?(shape, _method_name, args)
             return nil unless args.size == 1
@@ -1447,7 +1439,7 @@ module Rigor
             return nil unless arg.is_a?(Type::Constant)
 
             key = arg.value
-            return nil unless key.is_a?(Symbol) || key.is_a?(String)
+            return nil unless static_shape_key?(key)
 
             Type::Combinator.constant_of(shape.pairs.key?(key))
           end
@@ -1496,7 +1488,8 @@ module Rigor
           end
 
           # `shape.invert` — swaps keys and values. Folds when every value is a `Constant` whose value is a
-          # Symbol or String (the only hashable types that `HashShape` accepts as keys). Duplicate values
+          # scalar the carrier accepts as a key (Symbol / String / Integer / Float / true / false / nil;
+          # see {#static_shape_key?}). Duplicate values
           # would alias under inversion, so Rigor declines on collisions rather than silently dropping
           # entries.
           def hash_invert(shape, _method_name, args)
@@ -1504,7 +1497,7 @@ module Rigor
             return nil unless shape.closed?
             return nil unless shape.optional_keys.empty?
             return nil unless shape.pairs.values.all?(Type::Constant)
-            return nil unless shape.pairs.values.all? { |v| v.value.is_a?(Symbol) || v.value.is_a?(String) }
+            return nil unless shape.pairs.values.all? { |v| static_shape_key?(v.value) }
 
             inverted = shape.pairs.each_with_object({}) do |(k, v), acc|
               return nil if acc.key?(v.value)
@@ -1565,7 +1558,7 @@ module Rigor
             Type::Combinator.hash_shape_of(shape.pairs.merge(other.pairs))
           end
 
-          # `shape[k]` and `shape.fetch(k)` for a static symbol/string key. Missing-key resolution depends
+          # `shape[k]` and `shape.fetch(k)` for a value-pinned scalar key. Missing-key resolution depends
           # on the method:
           #
           # - `[]` returns `nil` at runtime; we surface `Constant[nil]` so the carrier is visible to
@@ -1599,13 +1592,13 @@ module Rigor
           end
 
           # Returns the per-step value type for a HashShape lookup (or `Constant[nil]` for a known-missing
-          # key). Returns `nil` when the argument is not a static symbol/string so the caller can fall
+          # key). Returns `nil` when the argument is not a value-pinned scalar key so the caller can fall
           # through to the projection answer.
           def hash_dig_step(shape, arg)
             return nil unless arg.is_a?(Type::Constant)
 
             key = arg.value
-            return nil unless key.is_a?(Symbol) || key.is_a?(String)
+            return nil unless static_shape_key?(key)
 
             if shape.pairs.key?(key)
               value = shape.pairs[key]
@@ -1631,7 +1624,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). Falls through when any argument is not a static symbol/string.
+          # behaviour). Falls through when any argument is not a value-pinned scalar key.
           def hash_values_at(shape, _method_name, args)
             return nil if args.empty?
 
@@ -1647,7 +1640,7 @@ module Rigor
           end
 
           # `shape.slice(:a, :b, ...)` — returns a sub-HashShape containing only the specified keys. All
-          # arguments must be `Constant[Symbol|String]`. Keys not present in the shape are silently
+          # arguments must be `Constant` scalar keys. Keys not present in the shape are silently
           # omitted (matching Ruby's runtime semantics — no nil padding). Declines on open shapes or when
           # any argument is not a static key.
           def hash_slice(shape, _method_name, args)
@@ -1660,7 +1653,7 @@ module Rigor
               return nil unless arg.is_a?(Type::Constant)
 
               key = arg.value
-              return nil unless key.is_a?(Symbol) || key.is_a?(String)
+              return nil unless static_shape_key?(key)
 
               requested << key
             end
@@ -1669,7 +1662,7 @@ module Rigor
           end
 
           # `shape.except(:a, :b, ...)` — returns a sub-HashShape with the specified keys removed. All
-          # arguments must be `Constant[Symbol|String]`. Keys not present in the shape are silently
+          # arguments must be `Constant` scalar keys. Keys not present in the shape are silently
           # ignored. Declines on open shapes or when any argument is not a static key.
           def hash_except(shape, _method_name, args)
             return nil if args.empty?
@@ -1681,7 +1674,7 @@ module Rigor
               return nil unless arg.is_a?(Type::Constant)
 
               key = arg.value
-              return nil unless key.is_a?(Symbol) || key.is_a?(String)
+              return nil unless static_shape_key?(key)
 
               excluded[key] = true
             end

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

@@ -12,13 +12,12 @@ module Rigor
       # `Data` path does not need: **mutation soundness.**
       #
       # A `Struct` instance is mutable (`s.x = v`, `s[:x] = v`, escape), so a member map bound to a
-      # variable can be invalidated by a later write. This slice (ADR-48 slices 1+2 in the sound
-      # *transient* form) folds a member read ONLY off a **fresh** instance — the transient receiver of a
-      # `.new(...).x` / `.with(...).x` chain, which provably cannot have been mutated between
-      # materialisation and the read. A member read off a *stored* binding degrades to `Dynamic[top]`
-      # rather than fold a possibly-stale value. Promoting the fold to mutation-free bound locals is the
-      # deferred slice 3 (relax the fresh-receiver gate to a fold-safe-local scan); precise mutated-member
-      # re-typing is slice 4.
+      # variable can be invalidated by a later write. A member read folds off a **fresh** instance (the
+      # transient receiver of a `.new(...).x` / `.with(...).x` chain, unmutatable between materialisation
+      # and the read — slices 1+2), off a **fold-safe stored local** the {Inference::StructFoldSafety} scan
+      # proved is never mutated / aliased / escaped (slice 3), or off a **setter-mutated fold-safe local**
+      # whose bindings {#apply_setter_writeback} keeps current (slice 4). Any other stored receiver degrades
+      # to `Dynamic[top]` rather than fold a possibly-stale value.
       #
       # Responsibilities:
       #
@@ -272,7 +271,8 @@ module Rigor
         end
 
         # A fold-safe stored receiver is a local-variable read whose name the body's fold-safe set (on the
-        # scope) marks as never mutated.
+        # scope) marks as safe to fold — never aliased / escaped, and any mutation a straight-line member
+        # setter the write-back keeps the binding current for.
         def fold_safe_local_receiver?(context)
           node = context.call_node
           receiver = node&.receiver
@@ -281,6 +281,38 @@ module Rigor
 
           scope.struct_fold_safe?(receiver.name)
         end
+
+        # ADR-48 slice 4 — precise mutated-member re-typing. After a `local.member = v` setter on a
+        # fold-safe `StructInstance` local, rebind the local to a `StructInstance` with that member replaced
+        # by the assigned type, so a later `local.member` read folds to the assigned value (and a sibling
+        # `local.other` stays precise). Called from `eval_call`'s post-call scope, mirroring
+        # `MutationWidening.widen_after_call`. Sound ONLY for a fold-safe local: the fold-safe scan proves it
+        # is never aliased / escaped and its setters are straight-line, so the binding this installs is the
+        # local's true member state at every later read on the path. A non-fold-safe local is left untouched
+        # (its reads do not fold, so the binding is never consulted for folding).
+        #
+        # @param call_node    [Prism::CallNode]  the `local.member = v` call
+        # @param assigned_type [Rigor::Type, nil] the setter's assigned value type (the call's own result)
+        # @param scope        [Rigor::Scope, nil]
+        # @return             [Rigor::Scope]     the (possibly) rebound scope
+        def apply_setter_writeback(call_node:, assigned_type:, scope:)
+          return scope if scope.nil? || assigned_type.nil?
+
+          receiver = call_node.receiver
+          return scope unless receiver.is_a?(Prism::LocalVariableReadNode)
+          return scope unless scope.struct_fold_safe?(receiver.name)
+
+          current = scope.local(receiver.name)
+          return scope unless current.is_a?(Type::StructInstance)
+
+          member = member_setter_target(call_node.name, current.members)
+          return scope if member.nil?
+
+          rebound = Type::Combinator.struct_instance_of(
+            members: current.members.merge(member => assigned_type), class_name: current.class_name
+          )
+          scope.with_local(receiver.name, rebound)
+        end
       end
     end
   end

data/lib/rigor/inference/method_dispatcher.rb

@@ -8,6 +8,7 @@ require_relative "../builtins/hkt_builtins"
 require_relative "../builtins/static_return_refinements"
 require_relative "dynamic_origin"
 require_relative "flow_tracer"
+require_relative "void_tail_summary"
 require_relative "method_dispatcher/call_context"
 require_relative "method_dispatcher/constant_folding"
 require_relative "method_dispatcher/literal_string_folding"
@@ -70,6 +71,14 @@ module Rigor
           block_type: block_type, environment: environment,
           call_node: call_node, scope: scope
         )
+        # ADR-100 WD4 — the transitive-void consult, HERE in the wrapper rather than in any result
+        # tier: which tier answers the intermediate's call depends on where the leaf's RBS came from
+        # (`RbsDispatch` on the ADR-93 synthesized `untyped` skeleton, or the post-dispatch
+        # `ExpressionTyper` body-inference tiers on a partial hand-written `sig/`), and both answers
+        # are correct types that must not change. Recording is therefore result-independent and
+        # type-blind; a statement-position record stays inert because the collector only reads value
+        # positions.
+        record_transitive_void_origin(receiver_type, method_name, call_node, scope)
         # `rigor trace` — record the dispatch outcome (resolved type, or the fail-soft `nil` the
         # caller widens to `Dynamic[Top]`).
         if FlowTracer.active?
@@ -225,6 +234,36 @@ module Rigor
         fallback_result
       end
 
+      # ADR-100 WD4 — records the transitive `-> void` provenance when the called method is a
+      # discovered project `def` whose {VoidTailSummary} chain ends in an author-declared `-> void`
+      # leaf on the same owner. Guards cheapest-first: the internal dispatcher callers nil `scope` /
+      # `call_node` out; the receiver must project through {#discovered_method_lookup}
+      # (`Nominal` / `Singleton` only — unions and `Dynamic` receivers stay out); and the
+      # `discovered_method?` pre-filter (two pure hash reads) keeps the hot path at ~zero cost —
+      # only a call that provably targets a discovered def of the right kind resolves the node and
+      # consults the summary. The `Prism::CallNode` guard mirrors `collect_plugin_contributions`:
+      # the `&:symbol` block path dispatches with the `Prism::BlockArgumentNode` itself, which is
+      # never a collector value position, so recording on it would be dead weight.
+      def record_transitive_void_origin(receiver_type, method_name, call_node, scope)
+        return if scope.nil? || call_node.nil?
+        return unless call_node.is_a?(Prism::CallNode)
+
+        class_name, kind = discovered_method_lookup(receiver_type)
+        return if class_name.nil?
+        return unless scope.discovered_method?(class_name, method_name, kind)
+
+        def_node =
+          if kind == :singleton
+            scope.singleton_def_for(class_name, method_name)
+          else
+            scope.user_def_for(class_name, method_name)
+          end
+        return if def_node.nil?
+
+        origin = VoidTailSummary.new(scope).origin_for(def_node, class_name, kind)
+        scope.record_void_origin(call_node, origin) if origin
+      end
+
       # v0.1.3 — discovered-method dispatch tier. `scope` carries the `discovered_methods` table
       # built once per program by `ScopeIndexer` (a `Hash[String, Hash[Symbol, :instance |
       # :singleton]]`). When the receiver names a discovered class AND the requested method is
@@ -701,7 +740,7 @@ module Rigor
       private_constant :STDLIB_SINGLETON_FOLDERS
 
       PRECISE_TIERS_TAIL = Ractor.make_shareable([
-        KernelDispatch, MethodFolding, ReduceFolding, ArrayToHFolding, BlockFolding
+        MethodFolding, ReduceFolding, ArrayToHFolding, BlockFolding
       ].freeze)
       private_constant :PRECISE_TIERS_TAIL
 
@@ -735,6 +774,9 @@ module Rigor
           return result if result
         end
 
+        kernel_result = dispatch_kernel_intrinsic(context)
+        return kernel_result if kernel_result
+
         PRECISE_TIERS_TAIL.each do |tier|
           result = tier.try_dispatch(context)
           return result if result
@@ -742,6 +784,20 @@ module Rigor
         nil
       end
 
+      # ADR-91 WD1 — the single dispatcher-held ownership gate for the Kernel module-function surface
+      # (gate-by-held-key, the same move STDLIB_SINGLETON_FOLDERS made above). The tier runs only when
+      # the method name is in the compiled `INTRINSIC_NAMES` table AND the call is attributable to
+      # Kernel itself (implicit self / `Kernel.` receiver, no discovered user redefinition). Because the
+      # gate lives HERE and nowhere else, a fold inside KernelDispatch that "forgets" its ownership
+      # guard is unrepresentable — the whole tier is unreachable for a foreign receiver. Unit probes
+      # calling `KernelDispatch.try_dispatch` directly keep the caller-vouches-for-ownership contract.
+      def dispatch_kernel_intrinsic(context)
+        return nil unless KernelDispatch::INTRINSIC_NAMES.include?(context.method_name)
+        return nil unless KernelDispatch.kernel_owned_call?(context)
+
+        KernelDispatch.try_dispatch(context)
+      end
+
       def try_user_class_fallback(receiver_type, environment, call_node, context)
         return nil if environment.nil?
 

data/lib/rigor/inference/mutation_widening.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../type"
+require_relative "../source/node_children"
 
 module Rigor
   module Inference
@@ -101,7 +102,8 @@ module Rigor
 
       # Returns a scope with the call's receiver widened, when the receiver is a
       # local-/instance-variable read whose current binding is a literal-shape carrier
-      # (`Tuple` / `HashShape`) AND the call name is a known in-place mutator for that shape.
+      # (`Tuple` / `HashShape`) or an empty-witness refinement (`non-empty-array` /
+      # `non-empty-hash`) AND the call name is a known in-place mutator for that shape.
       # Returns `current_scope` unchanged otherwise.
       #
       # @param call_node     [Prism::CallNode]
@@ -160,7 +162,7 @@ module Rigor
         # scope's locals) trigger widening, so descending into nested blocks is safe and
         # necessary for the hkt_registry-shape case (an outer collection mutated inside an
         # iterator block whose body is itself inside another block).
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           scope = walk_for_outer_mutations(child, scope)
         end
         scope
@@ -216,6 +218,30 @@ module Rigor
           return nil unless HASH_MUTATORS.include?(method_name)
 
           widen_hash_shape(type)
+        when Type::Difference
+          widen_difference(type, method_name)
+        end
+      end
+
+      # `non-empty-array[T]` / `non-empty-hash[K, V]` → the bare base nominal. These refinement
+      # carriers are what `empty?` / `any?` narrowing writes (ADR-47 §4-4), and they are just as
+      # invalidated by an in-place mutator as a `Tuple` is: `arr.clear` makes `arr` empty, so a
+      # surviving `Difference[Array[T], Tuple[]]` would project `arr.size` to `positive-int` and
+      # fold `arr.size == 0` to `Constant[false]` — a false `flow.always-falsey-condition` on
+      # correct code.
+      #
+      # Only the EMPTY-witness differences over Array / Hash are widened, and only for that
+      # base's mutator table. The other catalogued refinements are unreachable from these tables
+      # by construction: `non-empty-string` and `non-zero-int` bind String / Integer receivers,
+      # whose mutators (`String#<<` and friends) appear in neither `ARRAY_MUTATORS` nor
+      # `HASH_MUTATORS` — and none of them can empty a non-empty string anyway.
+      def widen_difference(difference, method_name)
+        return nil unless difference.removes_empty_witness?
+
+        base = difference.base
+        case base.class_name
+        when "Array" then ARRAY_MUTATORS.include?(method_name) ? base : nil
+        when "Hash" then HASH_MUTATORS.include?(method_name) ? base : nil
         end
       end
 
@@ -248,16 +274,24 @@ module Rigor
         Type::Combinator.nominal_of("Hash", type_args: [key_type, value_type])
       end
 
-      # Maps the literal Ruby key set (`Symbol` / `String`) to a union of the corresponding type
-      # carriers. We deliberately do NOT fold to a `Constant<:k1> | Constant<:k2>` union — that
-      # would be a precision improvement that complicates the widening contract; the goal here
-      # is to LOSE precision, not to record a new fact set.
+      # Maps the literal Ruby key set to a union of the corresponding type carriers. Symbol / String /
+      # Integer / Float keys widen to their class nominal; the `true` / `false` / `nil` singleton keys
+      # keep their constant carrier (the constant IS the class's whole value set, and `nil` reads better
+      # than `NilClass` in a widened `Hash[K, V]`). We deliberately do NOT fold the widenable kinds to a
+      # `Constant<:k1> | Constant<:k2>` union — that would be a precision improvement that complicates
+      # the widening contract; the goal here is to LOSE precision, not to record a new fact set.
       def key_union_for(keys)
-        kinds = keys.map { |k| k.is_a?(Symbol) ? "Symbol" : "String" }.uniq
-        carriers = kinds.map { |name| Type::Combinator.nominal_of(name) }
+        carriers = keys.map { |k| key_widening_carrier(k) }.uniq
         carriers.size == 1 ? carriers.first : Type::Combinator.union(*carriers)
       end
 
+      def key_widening_carrier(key)
+        case key
+        when true, false, nil then Type::Combinator.constant_of(key)
+        else Type::Combinator.nominal_of(key.class.name)
+        end
+      end
+
       # ----------------------------------------------------------------
       # ADR-56 slice C — receiver-content element-type JOIN.
       #