rigortype 0.2.9 → 0.3.0

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.
       #

data/lib/rigor/inference/narrowing.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../reflection"
+require_relative "../source/constant_path"
 require_relative "../type"
 require_relative "../environment"
 require_relative "../rbs_extended"
@@ -41,7 +42,13 @@ module Rigor
       TRUSTED_EQUALITY_LITERAL_CLASSES = [String, Symbol, Integer, TrueClass, FalseClass, NilClass].freeze
       SINGLETON_LITERAL_CLASSES = [TrueClass, FalseClass, NilClass].freeze
       ClassNarrowingContext = Data.define(:exact, :polarity, :environment)
-      private_constant :TRUSTED_EQUALITY_LITERAL_CLASSES, :SINGLETON_LITERAL_CLASSES, :ClassNarrowingContext
+      # A recognised `=~` regex pattern operand: the pattern `source` string and whether it was
+      # compiled in extended (`//x`) mode. Extraction from a literal `RegularExpressionNode` and from
+      # a value-pinned `Constant[Regexp]` share this carrier so the participation walk and the
+      # extended-mode bail read one shape.
+      RegexMatchPattern = Data.define(:source, :extended)
+      private_constant :TRUSTED_EQUALITY_LITERAL_CLASSES, :SINGLETON_LITERAL_CLASSES, :ClassNarrowingContext,
+                       :RegexMatchPattern
 
       module_function
 
@@ -962,8 +969,8 @@ module Rigor
         end
 
         def simple_dispatch_name?(name)
-          %i[nil? ! is_a? kind_of? instance_of? == != === =~ key? has_key? empty? any? none?
-             respond_to?].include?(name)
+          %i[nil? ! is_a? kind_of? instance_of? == != === =~ match? key? has_key? empty? any?
+             none? respond_to?].include?(name)
         end
 
         def dispatch_call_simple(node, scope, name)
@@ -974,6 +981,7 @@ module Rigor
           when :==, :!= then analyse_equality_predicate(node, scope, equality: name)
           when :=== then analyse_case_equality_predicate(node, scope)
           when :=~ then analyse_regex_match_predicate(node, scope)
+          when :match? then analyse_whole_regex_match_predicate(node, scope)
           when :key?, :has_key? then analyse_key_presence_predicate(node, scope)
           when :empty?, :any?, :none? then analyse_array_emptiness_predicate(node, scope, name)
           when :respond_to? then analyse_respond_to_predicate(node, scope)
@@ -1199,30 +1207,123 @@ module Rigor
         # - Falsey edge (`=~` returned nil — no match): `$~` and every numbered / back-reference
         #   global bound to `Constant<nil>`.
         #
-        # Returns nil (no narrowing) when the receiver / argument pair does not include a
-        # `RegularExpressionNode` literal we can count.
+        # Returns nil (no narrowing) when the receiver / argument pair does not resolve to exactly one
+        # regex pattern we can count (see {#regex_match_pattern}).
         def analyse_regex_match_predicate(node, scope)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
 
-          regex_node = regex_match_literal(node.receiver, node.arguments.arguments.first)
-          return nil if regex_node.nil?
+          arg = node.arguments.arguments.first
+          pattern = regex_match_pattern(node.receiver, arg, scope)
+          return nil if pattern.nil?
+          # Extended mode (`//x`) lets the pattern carry free whitespace and `#` comments, and a
+          # comment may contain a literal `(` — which the light char-scan walker would miscount as a
+          # capturing group, shifting `$N` indices and narrowing the wrong global. That is a
+          # false-negative-class misnarrowing, so bail rather than risk it. The literal path shares
+          # this bail: `RegularExpressionNode` carries the same latent miscount.
+          return nil if pattern.extended
+
+          unconditional = unconditional_capture_groups(pattern.source)
+          truthy, falsey = regex_match_predicate_scopes(scope, unconditional)
+          # #164 — layer whole-receiver refinement onto the truthy edge without disturbing the
+          # match-global logic above. A successful `str =~ /\A\d+\z/` proves the WHOLE string
+          # matched, so the string operand narrows to the imported refinement the anchored pattern
+          # names. The falsey edge is untouched: a failed match proves nothing about the shape.
+          truthy = apply_whole_receiver_refinement(truthy, node.receiver, arg, pattern.source, scope)
+          [truthy, falsey]
+        end
+
+        # `str.match?(/\A\d+\z/)` — `String#match?` is a pure boolean predicate whose truthy edge
+        # proves a property of the ENTIRE receiver. When the argument is a fully `\A…\z`-anchored
+        # single-char-class pattern recognised by {RegexRefinement.for_whole_pattern}, narrow the
+        # receiver local to the matching imported refinement on the truthy edge; the falsey edge
+        # passes through unchanged (failing one pattern proves nothing about the string's shape).
+        # A non-literal / unanchored / `\Z` / line-anchored / `//x` pattern falls through to no
+        # narrowing.
+        def analyse_whole_regex_match_predicate(node, scope)
+          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
+          return nil if node.arguments.nil? || node.arguments.arguments.size != 1
 
-          unconditional = unconditional_capture_groups(regex_node.unescaped)
-          regex_match_predicate_scopes(scope, unconditional)
+          pattern = regex_operand_pattern(node.arguments.arguments.first, scope)
+          return nil unless pattern.is_a?(RegexMatchPattern)
+          return nil if pattern.extended
+
+          refinement = ::Rigor::Builtins::RegexRefinement.for_whole_pattern(pattern.source)
+          return nil if refinement.nil?
+
+          local_name = node.receiver.name
+          return nil if scope.local(local_name).nil?
+
+          [scope.with_local(local_name, refinement), scope]
         end
 
-        def regex_match_literal(left, right)
-          return left if left.is_a?(Prism::RegularExpressionNode)
-          return right if right.is_a?(Prism::RegularExpressionNode)
+        # Narrows the string operand of a `=~` predicate to a whole-receiver refinement when the
+        # regex source is a recognised `\A…\z`-anchored pattern. Returns the (possibly unchanged)
+        # truthy scope; the falsey edge is never touched by this layer.
+        def apply_whole_receiver_refinement(truthy, receiver, arg, source, scope)
+          refinement = ::Rigor::Builtins::RegexRefinement.for_whole_pattern(source)
+          return truthy if refinement.nil?
 
-          nil
+          # `regex_match_pattern` already resolved the regex operand from a literal or a
+          # `Constant[Regexp]` constant read — never a bare local — so the string subject is
+          # unambiguously the local-read operand, if either operand is one.
+          subject = [receiver, arg].find { |operand| operand.is_a?(Prism::LocalVariableReadNode) }
+          return truthy if subject.nil? || scope.local(subject.name).nil?
+
+          truthy.with_local(subject.name, refinement)
         end
 
-        # Curated set of back-reference globals bound by every
-        # `=~`. Numbered references (`$1..$N`) are handled
-        # separately because N depends on the regex source.
-        REGEX_MATCH_GLOBALS = %i[$~ $& $` $' $+].freeze
+        # Recognises the regex pattern operand of a `=~` predicate. An operand resolves to a regex when
+        # it is either a syntactic `RegularExpressionNode` literal OR a constant read whose type is a
+        # value-pinned `Constant[Regexp]` (`RE = /.../` and `RE = Regexp.new(...)` both fold to the
+        # carrier in the whole-program constant pre-pass). Returns a single {RegexMatchPattern}, or nil
+        # (no narrowing) when NEITHER operand resolves to a regex, when BOTH do (`/a/ =~ /b/` — no
+        # string subject to bind), or when a constant operand is ambiguous — typed as a `Union` from a
+        # twice-assigned constant, where no single source can be pinned.
+        def regex_match_pattern(left, right, scope)
+          left_pattern = regex_operand_pattern(left, scope)
+          right_pattern = regex_operand_pattern(right, scope)
+          return nil if left_pattern == :ambiguous || right_pattern == :ambiguous
+
+          patterns = [left_pattern, right_pattern].grep(RegexMatchPattern)
+          patterns.size == 1 ? patterns.first : nil
+        end
+
+        # Classifies one `=~` operand: a {RegexMatchPattern} when it resolves to a regex (literal or
+        # `Constant[Regexp]`), `:ambiguous` when a constant operand types as a `Union` (a twice-assigned
+        # constant), or nil when the operand is not a regex at all.
+        def regex_operand_pattern(node, scope)
+          case node
+          when Prism::RegularExpressionNode
+            RegexMatchPattern.new(source: node.unescaped, extended: node.extended?)
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            regex_operand_from_constant(node, scope)
+          end
+        end
+
+        # Resolves a constant-reference operand to a regex pattern via the shared lexical-constant
+        # resolution (`Reflection.resolve_constant_type`). `Regexp#options` gives the real
+        # extended-mode flag; `Regexp#source` the pattern. Returns `:ambiguous` for a `Union`-typed
+        # constant so the caller bails, and nil when the constant does not resolve to a `Constant[Regexp]`.
+        def regex_operand_from_constant(node, scope)
+          name = Source::ConstantPath.qualified_name_or_nil(node)
+          return nil if name.nil?
+
+          type = Reflection.resolve_constant_type(name, scope: scope)
+          return :ambiguous if type.is_a?(Type::Union)
+          return nil unless type.is_a?(Type::Constant)
+
+          value = type.value
+          return nil unless value.is_a?(Regexp)
+
+          RegexMatchPattern.new(source: value.source, extended: value.options.anybits?(Regexp::EXTENDED))
+        end
+
+        # Curated set of match globals bound non-nil on every successful `=~` regardless of grouping:
+        # `$~` (the MatchData), `$&` (whole match), `` $` `` (pre-match), `$'` (post-match). Numbered
+        # references (`$1..$N`) and `$+` (the last matched group) are handled separately because they
+        # depend on the regex source — `$+` is gated on the same participation set as `$N` (#177).
+        REGEX_MATCH_GLOBALS = %i[$~ $& $` $'].freeze
         private_constant :REGEX_MATCH_GLOBALS
 
         # `unconditional` is the Set of 1-based numbered-capture indices whose group is
@@ -1251,6 +1352,15 @@ module Rigor
             truthy = truthy.with_global(name, string_t)
             falsey = falsey.with_global(name, nil_t)
           end
+          # `$+` is the LAST matched group, so it is nil on a successful match whose groups are all
+          # optional (`"b" =~ /(a)?b/` matches yet leaves `$+` nil) or absent (no capture group). It
+          # narrows to `String` only when some group is guaranteed to participate — the same
+          # participation gate `$N` uses (#177). With no unconditional group it is left unbound on both
+          # edges (fall through to the RBS `String?` default), exactly as an optional `$N` is.
+          unless unconditional.empty?
+            truthy = truthy.with_global(:$+, string_t)
+            falsey = falsey.with_global(:$+, nil_t)
+          end
           [truthy, falsey]
         end