rigortype 0.4.6 → 0.4.7

data/lib/rigor/inference/mutation_widening.rb

@@ -10,7 +10,10 @@ require_relative "mutation_rejoin"
 require_relative "deep_erasure"
 require_relative "receiver_alias"
 require_relative "refinement_mutation"
+# `RemoverNarrowing` is loaded with the engine (`scope.rb`), not here: the engine-free value layer requires this file
+# and must not pull in the remover narrowing and its holder scan (`spec/rigor/cli/effects_cache_probe_spec.rb`).
 require_relative "rewrite_mutation"
+require_relative "set_mutation"
 require_relative "string_mutation"
 
 module Rigor
@@ -19,8 +22,7 @@ module Rigor
     # AND whose method is a known in-place mutator.
     #
     # Closes the **G1 / G2** flow-folding gaps documented at
-    # `docs/notes/20260521-mastodon-cluster4-flow-folding-triage.md` and queued in
-    # [`docs/CURRENT_WORK.md`](../../../docs/CURRENT_WORK.md) § "Flow-folding". The user-visible
+    # `docs/notes/20260521-mastodon-cluster4-flow-folding-triage.md`. The user-visible
     # symptom they shared was a spurious `flow.always-truthy-condition` on a `arr.size == N` /
     # `arr.empty?` / `@arr.empty?` check that follows a loop body or sibling method that mutates
     # `arr` / `@arr` in place.
@@ -76,6 +78,7 @@ module Rigor
     #   ARE also handled** (ivars live in the method-body scope, not the block-local scope).
     #
     # The remaining three items above are demand-gated; see ADR-56.
+    # rubocop:disable-next Metrics/ModuleLength
     module MutationWidening
       # Array mutators that change either the size or the element set of a literal-shape carrier
       # (Tuple). Receiver-mutating methods only — non-mutating siblings (`map` vs `map!`,
@@ -107,7 +110,8 @@ module Rigor
       # Every method name {#widen_for_mutator} responds to — the one set a body scan asks "could an
       # in-place call on this name change its binding?" against (issue #587: the block-return
       # threading gate). Derived from the tables rather than spelled out, so the scan and the
-      # widening it predicts cannot drift apart.
+      # widening it predicts cannot drift apart. The Set-only names ({SetMutation::MUTATORS}) stay out: the scans read
+      # a name without its receiver, and `merge` on a Hash returns a new Hash (issue #2294).
       SHAPE_MUTATORS = (ARRAY_MUTATORS | HASH_MUTATORS | HashLookupMutation::MUTATORS | StringMutation::MUTATORS).freeze
 
       # Methods that return the receiver (or a shallow copy) and cannot mutate it. They must not
@@ -134,10 +138,61 @@ module Rigor
       # pre-join behaviour exactly.
       NO_ARG_TYPES = [].freeze
 
-      def widen_after_call(call_node:, current_scope:, arg_types: NO_ARG_TYPES)
+      # `rewritten_element` is the element a typed element rewriter stores ({RewriteMutation.typed}), or `nil`.
+      def widen_after_call(call_node:, current_scope:, arg_types: NO_ARG_TYPES, rewritten_element: nil)
         return current_scope if pure_self_returner?(call_node.name)
 
-        widen_receiver_aliases(call_node.receiver, call_node.name, current_scope, arg_types: arg_types)
+        if RemoverNarrowing.candidate?(call_node)
+          narrowed = narrow_remover_receiver(call_node, current_scope, arg_types)
+          return narrowed if narrowed
+        end
+
+        widen_receiver_aliases(call_node.receiver, call_node.name, current_scope, arg_types:, rewritten_element:,
+                                                                                  removes_nil: removes_nil?(call_node))
+      end
+
+      # Issue #2608 — a remover that narrows its receiver by what it removes ({RemoverNarrowing}): the receiver's
+      # binding widens as any mutator's does, then loses what the call provably took out. This answers before the
+      # #2555 remover floor, so a synthesised carrier a store grew keeps its precise reading (`parts << maybe_nil;
+      # parts.compact!` reads `Array[String]`). `nil` when the call narrows nothing; the caller then takes the
+      # ordinary path, the floor included.
+      def narrow_remover_receiver(call_node, scope, arg_types)
+        read = call_node.receiver
+        getter, builder = ALIAS_ACCESSORS[read.class]
+        name = ReceiverAlias.read_name(read)
+        current = scope.public_send(getter, name)
+        return nil if current.nil? || RemoverHolderScan.unsafe_receiver?(scope, name)
+
+        narrowed = RemoverNarrowing.narrow_shape(current, call_node)
+        if narrowed.nil?
+          synthesised = synthesised_binding?(scope, getter, name)
+          base = widen_for_mutator(current, call_node.name, arg_types:, synthesised:)
+          narrowed = RemoverNarrowing.narrow(base || current, call_node, scope)
+        end
+        return nil if narrowed.nil?
+        return scope if narrowed == current
+
+        MutationRejoin.rebind(scope, builder, name, narrowed, pre_state: current, kind: getter)
+      end
+
+      # Issue #2555 — the removers that may take a `nil` out, which is every one but a `delete` / `delete?` given a
+      # non-nil literal: false positives outrank, so a positional remover (`pop`, `shift`, `slice!`), `subtract`
+      # (whose argument may hold `nil`) and a `delete` of an unknown value count. `Hash#delete` removes by key, so
+      # whatever value the key held may go ({.floor_grown_carrier} reads the receiver for it).
+      NIL_REMOVERS = %i[compact! reject! select! filter! delete_if keep_if clear pop shift slice!
+                        subtract].to_set.freeze
+      NON_NIL_LITERALS = [
+        Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode, Prism::ImaginaryNode, Prism::StringNode,
+        Prism::SymbolNode, Prism::TrueNode, Prism::FalseNode
+      ].freeze
+      private_constant :NON_NIL_LITERALS
+
+      def removes_nil?(call_node)
+        return true if NIL_REMOVERS.include?(call_node.name)
+        return false unless %i[delete delete?].include?(call_node.name)
+
+        argument = call_node.arguments&.arguments&.first
+        NON_NIL_LITERALS.none? { |klass| argument.is_a?(klass) }
       end
 
       # True when `receiver` names at least one variable whose CURRENT binding is a literal-shape
@@ -148,10 +203,19 @@ module Rigor
 
         ReceiverAlias.mutated_reads(receiver).any? do |read|
           getter, = ALIAS_ACCESSORS[read.class]
-          getter && shape_carrier?(scope.public_send(getter, ReceiverAlias.read_name(read)))
+          next false if getter.nil?
+
+          name = ReceiverAlias.read_name(read)
+          shape_carrier?(scope.public_send(getter, name), synthesised: synthesised_binding?(scope, getter, name))
         end
       end
 
+      # Issue #2555 L3 — whether the binding `getter` / `name` reads carries the `:synthesised` construction fact
+      # ({Scope#construction_fact?}). Only a local can: an instance, class or global variable never carries one.
+      def synthesised_binding?(scope, getter, name)
+        getter == :local && scope.construction_fact?(name)
+      end
+
       # A union carrying a shape member is joinable too (issue #645): {#widen_union} widens that
       # member through the same join, so the arguments the caller would skip are the evidence it
       # needs.
@@ -160,26 +224,32 @@ module Rigor
       # An empty-witness `Difference` counts too (issue #936): the `non-empty-array[T]` arm joins the
       # mutator's added element now, so its arguments are evidence this seam consumes rather than
       # arguments nothing will read.
-      def shape_carrier?(type)
+      # A precise `Hash` counts too when its binding carries the `:synthesised` construction fact (issue #2555): the
+      # re-join grows it from these arguments.
+      def shape_carrier?(type, synthesised: false)
         case type
         when Type::Tuple, Type::HashShape then true
-        when Type::Constant then StringMutation.constant?(type)
+        when Type::Constant then StringMutation.constant?(type) || SetMutation.constant?(type)
         # A re-openable nominal counts since issue #580: skipping it made the one-way door
         # self-fulfilling, since the arm never saw the arg types it grows from.
-        when Type::Nominal then MutationRejoin.regrowable_carrier?(type)
+        # A precise `Array[E]` / `Set[E]` counts since issue #2361, which re-grows it from these arguments.
+        when Type::Nominal
+          MutationRejoin.regrowable_carrier?(type) || MutationRejoin.precise_array?(type) ||
+            SetMutation.regrowable?(type) || (synthesised && MutationRejoin.synthesised_carrier?(type))
         when Type::Difference then type.removes_empty_witness?
-        when Type::Union then type.members.any? { |m| shape_carrier?(m) }
+        when Type::Union then type.members.any? { |m| shape_carrier?(m, synthesised:) }
         else false
         end
       end
 
       # Widens every variable `receiver` can evaluate to ({ReceiverAlias.mutated_reads}), against `method_name`'s
       # mutator table.
-      def widen_receiver_aliases(receiver, method_name, current_scope, arg_types: NO_ARG_TYPES)
+      def widen_receiver_aliases(receiver, method_name, current_scope, arg_types: NO_ARG_TYPES, rewritten_element: nil,
+                                 removes_nil: false)
         return current_scope if receiver.nil?
 
         ReceiverAlias.mutated_reads(receiver).reduce(current_scope) do |acc, read|
-          widen_alias_read(method_name, read, acc, arg_types: arg_types)
+          widen_alias_read(method_name, read, acc, arg_types:, rewritten_element:, removes_nil:)
         end
       end
 
@@ -196,9 +266,8 @@ module Rigor
       # always safe — it can only LOSE precision — so blindly propagating is sound regardless of
       # whether the block actually runs.
       #
-      # Recurses into nested expression nodes so chained / nested forms (`arr << f(x); arr <<
-      # g(y)`, `arr.push(x) if cond`) are all caught. Does NOT recurse into nested
-      # `Prism::BlockNode`s — each block is processed by its own `eval_call`.
+      # Recurses into every nested node, blocks included, so chained / nested forms (`arr << f(x); arr <<
+      # g(y)`, `arr.push(x) if cond`) are all caught.
       def widen_after_block(call_node:, outer_scope:)
         block = call_node.block
         return DeepErasure.widen_symbol_proc(call_node, outer_scope) if DeepErasure.symbol_proc_mutation?(block)
@@ -235,6 +304,9 @@ module Rigor
         receiver = call_node.receiver
         return scope if receiver.nil?
 
+        widened = widen_outer_element_read(call_node, scope)
+        return widened if widened
+
         ReceiverAlias.candidates(receiver).reduce(scope) do |acc, read|
           # A block-local read ({ReceiverAlias.block_local?}: a `depth == 0` local, or `it`) is not a
           # capture of the outer scope, so widening its name against the OUTER scope would hit an
@@ -245,10 +317,27 @@ module Rigor
           # after it re-adds the appended values' types onto the widened seed, so the seed's own value
           # pinning is still justified (`out = [0]; arr.each { out << x }` never rewrites slot 0). The
           # straight-line paths have no such join, which is why their default is `:widen` (issue #560).
-          widen_alias_read(call_node.name, read, acc, values: :keep)
+          widen_alias_read(call_node.name, read, acc, values: :keep, unread_arguments: !call_node.arguments.nil?)
         end
       end
 
+      # Issue #2287 — a mutator on an element read rooted at a captured local (`[0].each { |i| a[i] << 2 }`,
+      # `loop { a[0] << 2; break }`) mutates an element the outer binding still carries, and names no variable
+      # {ReceiverAlias.candidates} could widen. The element at that path widens in the outer scope as the
+      # straight-line {ElementReadWidening.widen_element_read} widens it; a block-local root is skipped as a
+      # block-local read is. Answers the widened scope, or `nil` when the receiver is no such read or nothing widened.
+      def widen_outer_element_read(call_node, scope)
+        path = ElementReadWidening.element_read_path(call_node.receiver)
+        return nil if path.nil?
+
+        read, steps = path
+        return nil if ReceiverAlias.block_local?(read)
+
+        current = scope.local(read.name)
+        widened = current && ElementReadWidening.widen_through_path(current, steps, call_node.name, NO_ARG_TYPES)
+        widened && scope.with_mutated_local(read.name, widened)
+      end
+
       # The arms per kind of binding differ only in which pair of `Scope` accessors they use, so they are read out
       # of one table rather than written once per kind: a carrier the widening responds to must not be widened on
       # one kind of binding and left on another. `$g << x; $g == "k"` folded always-truthy on a `$g` Ruby holds
@@ -262,16 +351,37 @@ module Rigor
                                                 Prism::GlobalVariableReadNode => %i[global with_global]
                                               })
 
-      def widen_alias_read(method_name, read, scope, values: :widen, arg_types: NO_ARG_TYPES)
+      # `unread_arguments` says the call passes arguments this seam did not type (the block-capture path): a Set,
+      # which has no block content join, takes one unknown store for it ({SetMutation.widen}).
+      def widen_alias_read(method_name, read, scope, values: :widen, arg_types: NO_ARG_TYPES, unread_arguments: false, # rubocop:disable Metrics/ParameterLists
+                           rewritten_element: nil, removes_nil: false)
         getter, builder = ALIAS_ACCESSORS[read.class]
         return scope if getter.nil?
 
         name = ReceiverAlias.read_name(read)
         current = scope.public_send(getter, name)
-        widened = widen_for_mutator(current, method_name, values: values, arg_types: arg_types)
-        return scope if widened.nil?
+        synthesised = synthesised_binding?(scope, getter, name)
+        if synthesised && MutationRejoin.floors_grown_carrier?(scope, name, method_name)
+          return floor_grown_carrier(scope, builder, name, current, method_name, getter, removes_nil)
+        end
 
-        MutationRejoin.rebind(scope, builder, name, widened, pre_state: current, kind: getter)
+        widened = widen_for_mutator(current, method_name, values:, arg_types:, unread_arguments:, rewritten_element:,
+                                                          synthesised:)
+        scope = MutationRejoin.rebind(scope, builder, name, widened, pre_state: current, kind: getter) if widened
+        return scope unless synthesised && MutationRejoin.content_adder?(method_name)
+
+        MutationRejoin.grew_unfloored?(current, widened) ? scope.with_construction_fact(name, :grown) : scope
+      end
+
+      # Issue #2555 — a remover or filter on a synthesised carrier a store has grown. Nothing narrows the carrier back,
+      # so the stored arm would outlive the values the call removes (`parts << nil; parts.compact!`); the carrier takes
+      # the `Dynamic[top]` floor it would have carried without the fact. The binding keeps its facts: the floored
+      # carrier is gradual, so the synthesised re-join no longer applies to it, and a later remover floors it again.
+      def floor_grown_carrier(scope, builder, name, current, method_name, getter, removes_nil)
+        drop_nil = removes_nil || (method_name == :delete && MutationRejoin.hash_carrier?(current))
+        floored = MutationRejoin.floor_parameters(current, drop_nil:)
+        floored = widen_for_mutator(floored, method_name) || floored
+        MutationRejoin.rebind(scope, builder, name, floored, pre_state: current, kind: getter)
       end
 
       # Mutators that can land a NEW value in an EXISTING slot, falsifying that slot's value pinning
@@ -285,15 +395,32 @@ module Rigor
       # Returns the widened type for a binding whose receiver is about to be mutated by
       # `method_name`, or `nil` when no widening applies (binding is not a carrier the mutation
       # stands for, OR the method is not a mutator for that shape, OR the carrier is a PRECISE
-      # nominal, whose element set is a claim this seam may not grow — see {MutationRejoin.regrowable_carrier?}).
-      def widen_for_mutator(type, method_name, values: :widen, arg_types: NO_ARG_TYPES)
+      # nominal the call stores nothing into — see {MutationRejoin.widen_precise_array}).
+      # A `rewritten_element` answers first for the carriers {RewriteMutation.typed} types (issue #2427).
+      # `synthesised` says the binding carries the `:synthesised` construction fact (issue #2555,
+      # {Scope#construction_fact?}): a precise nominal or Set it holds re-grows without the `Dynamic[top]` floor
+      # ({MutationRejoin.widen_synthesised}, {SetMutation.widen}).
+      def widen_for_mutator(type, method_name, values: :widen, arg_types: NO_ARG_TYPES, unread_arguments: false,
+                            rewritten_element: nil, synthesised: false)
+        typed = rewritten_element && type && RewriteMutation.typed(type, method_name, rewritten_element)
+        return typed == type ? nil : typed if typed
+
+        widen_carrier(type, method_name, values:, arg_types:, unread_arguments:, rewritten_element:, synthesised:)
+      end
+
+      # {#widen_for_mutator} for a carrier no typed element rewrite answered.
+      def widen_carrier(type, method_name, values:, arg_types:, unread_arguments:, rewritten_element:,
+                        synthesised: false)
         values = :keep unless VALUE_REWRITING_MUTATORS.include?(method_name)
         values = RewriteMutation.values_mode(type, method_name, values)
 
         return nil if type.nil?
+        if SetMutation.set?(type)
+          return SetMutation.widen(type, method_name, arg_types, unread_arguments:, synthesised:)
+        end
 
         case type
-        when Type::Nominal then MutationRejoin.widen_nominal(type, method_name, values:, arg_types:)
+        when Type::Nominal then MutationRejoin.widen_nominal(type, method_name, values:, arg_types:, synthesised:)
         when Type::Tuple
           return nil unless ARRAY_MUTATORS.include?(method_name)
 
@@ -307,7 +434,7 @@ module Rigor
         when Type::Difference
           widen_difference(type, method_name, arg_types: arg_types)
         when Type::Union
-          widen_union(type, method_name, values: values, arg_types: arg_types)
+          widen_union(type, method_name, values:, arg_types:, unread_arguments:, rewritten_element:, synthesised:)
         end
       end
 
@@ -325,12 +452,14 @@ module Rigor
       #
       # `nil` when no member widened — a union with no carrier member, or one whose carriers are
       # already nominal, is untouched exactly as the scalar path leaves them.
-      def widen_union(union, method_name, values: :widen, arg_types: NO_ARG_TYPES)
+      def widen_union(union, method_name, values: :widen, arg_types: NO_ARG_TYPES, unread_arguments: false,
+                      rewritten_element: nil, synthesised: false)
         widened_any = false
         members = union.members.map do |member|
           next member unless mutation_carrier?(member, method_name)
 
-          widened = widen_for_mutator(member, method_name, values: values, arg_types: arg_types)
+          widened = widen_for_mutator(member, method_name, values:, arg_types:, unread_arguments:, rewritten_element:,
+                                                           synthesised:)
           next member if widened.nil?
 
           widened_any = true
@@ -348,7 +477,8 @@ module Rigor
         (ARRAY_MUTATORS.include?(method_name) && ContentJoin.array_residue(member).empty?) ||
           ((HASH_MUTATORS.include?(method_name) || HashLookupMutation::MUTATORS.include?(method_name)) &&
             ContentJoin.hash_residue(member).empty?) ||
-          (StringMutation::MUTATORS.include?(method_name) && StringMutation.constant?(member))
+          (StringMutation::MUTATORS.include?(method_name) && StringMutation.constant?(member)) ||
+          (SetMutation::MUTATORS.include?(method_name) && SetMutation.carrier?(member))
       end
 
       # Joins the element evidence the mutator's own ARGUMENTS introduce into the already-widened

data/lib/rigor/inference/narrowing.rb

@@ -608,6 +608,26 @@ module Rigor
         truthy
       end
 
+      # Issue #2443 — `scope` with what every match binds, laid over the bindings it holds, for the block of a call
+      # that yields only after it has matched in the caller's frame ({MatchRebinding::YieldingMatch}): `$~` a
+      # `MatchData`, and `$&` and the pre- and post-match a `String`. The numbered groups and `$+` keep the bindings
+      # `scope` gives them. Typing them from the call's own pattern needs the group walk
+      # ({#unconditional_capture_groups}) to read every source right, which it does not yet (#2472), and forgetting
+      # them would report a group an earlier match in the method narrowed.
+      def yielded_match_scope(scope)
+        string_t = Type::Combinator.nominal_of("String")
+        scope.with_global(:$~, Type::Combinator.nominal_of("MatchData"))
+             .with_global(:$&, string_t).with_global(:$`, string_t).with_global(:$', string_t)
+      end
+
+      # Issue #2443 — true when every member of `type` is a String (a project subclass included) or a `Dynamic` that
+      # is untyped or may hold only Strings, Symbols and nil ({#match_member_kind}). A `nil` member never runs the
+      # block, so it counts neither way.
+      def string_match_receiver?(type, scope)
+        kinds = match_member_kinds(type, scope) - [:nil]
+        !kinds.empty? && kinds.all? { |kind| %i[string string_subclass dynamic].include?(kind) }
+      end
+
       # Internal analyser. Returns `[truthy_scope, falsey_scope]` when the predicate shape is
       # recognised, or `nil` to signal "no narrowing" so the public surface can fall back to the
       # entry scope. Issue #1359 — a condition whose value is a `gets`-family reader's, the bare call
@@ -968,12 +988,22 @@ module Rigor
         end
 
         def analyse_local_read(node, scope)
-          current = scope.local(node.name)
+          local_truthiness_edges(node.name, scope)
+        end
+
+        # The falsey edge is where an optimistic lookup's miss lands (ADR-101, issue #2306): `Scope#with_local`
+        # drops the issue #286 mark as a write does, so the edge re-takes the one `scope` holds. Without it the
+        # join after `if v; …; end` with no `else` lost the mark on both arms and read `v` as nil-free, although
+        # a miss reaches that join through the implicit else. The truthy edge proves the value non-nil, so it
+        # keeps dropping the mark.
+        def local_truthiness_edges(name, scope)
+          current = scope.local(name)
           return nil if current.nil?
 
+          falsey = scope.with_local(name, narrow_falsey(current))
           [
-            scope.with_local(node.name, narrow_truthy(current)),
-            scope.with_local(node.name, narrow_falsey(current))
+            scope.with_local(name, narrow_truthy(current)),
+            OptimisticOrigin.carry_local_mark(scope, falsey, name, nil)
           ]
         end
 
@@ -987,13 +1017,7 @@ module Rigor
         # holds the just-bound value; the narrowing contract on the surrounding `if` is the
         # same.
         def analyse_local_write(node, scope)
-          current = scope.local(node.name)
-          return nil if current.nil?
-
-          [
-            scope.with_local(node.name, narrow_truthy(current)),
-            scope.with_local(node.name, narrow_falsey(current))
-          ]
+          local_truthiness_edges(node.name, scope)
         end
 
         # Truthy guard on an instance variable. Covers both the bare read — `if @ivar`, the
@@ -1007,9 +1031,11 @@ module Rigor
           current = scope.ivar(node.name)
           return nil if current.nil?
 
+          # The falsey edge keeps the optimistic mark, as {#local_truthiness_edges} explains.
+          falsey = scope.with_ivar(node.name, narrow_falsey(current))
           [
             scope.with_ivar(node.name, narrow_truthy(current)),
-            scope.with_ivar(node.name, narrow_falsey(current))
+            OptimisticOrigin.carry_ivar_mark(scope, falsey, node.name, nil)
           ]
         end
 
@@ -1180,15 +1206,6 @@ module Rigor
           refinements
         end
 
-        # Recognised CallNode predicates:
-        # - `recv.nil?` (Slice 6 phase 1, no args, no block)
-        # - unary `!recv` (`name == :!`, no args, no block)
-        # - `recv.is_a?(C)` / `recv.kind_of?(C)` / `recv.instance_of?(C)` with a single
-        #   static-constant argument and no block (Slice 6 phase 2 sub-phase 1).
-        # - `local == literal` / `literal == local` and the `!=` mirror for trusted static
-        #   literals (Slice 6 phase 2 sub-phase 2).
-        # Anything else returns nil so the surrounding analyser falls through to the
-        # no-narrowing fallback.
         # Issue #1223 — `(x = e).nil?`, `(x ||= e).empty?`, `(@x = e).is_a?(C)`. A write's value is the binding
         # it leaves, and a predicate is narrowed in the scope after its receiver ran, so the call narrows the
         # variable exactly as the same call on a read of it would. Every analyser keys its receiver on a read
@@ -2466,10 +2483,10 @@ module Rigor
           narrowed == original ? :relational : :local_binding
         end
 
-        # `recv.is_a?(C)` / `recv.kind_of?(C)` / `recv.instance_of?(C)` narrowing. The receiver
-        # MUST be a `LocalVariableReadNode` (so we have a name to rebind), and the argument
+        # `recv.is_a?(C)` / `recv.kind_of?(C)` / `recv.instance_of?(C)` narrowing. The argument
         # MUST be a single static constant reference (`Foo` or `Foo::Bar`) we can resolve to a
-        # qualified class name. Anything else falls through to "no narrowing".
+        # qualified class name. The receiver is a local, a global, constant or instance variable
+        # ({#receiver_slot}) or a single-hop chain; anything else falls through to "no narrowing".
         def analyse_class_predicate(node, scope, exact:)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
@@ -2538,14 +2555,13 @@ module Rigor
           class_predicate_scopes(scope, node.receiver.name, current, class_name, exact: exact)
         end
 
-        # Stable single-hop method-chain narrowing (ROADMAP § Future cycles — "Method-call
-        # receiver narrowing across stable receivers"). When the predicate's receiver is
+        # Stable single-hop method-chain narrowing. When the predicate's receiver is
         # `<local/ivar>.<method>` with no args and no block, record the truthy / falsey
         # narrowing in `Scope#method_chain_narrowings` keyed on the chain address. The
         # dominated body's identical chain reads then observe the narrowed type through
         # `ExpressionTyper#call_type_for`'s lookup.
         #
-        # Heuristic-by-design (ROADMAP § "Soundness gap"): a second call to `x.last` could in
+        # Heuristic-by-design: a second call to `x.last` could in
         # principle return a different value than the first. The chain is dropped on (1)
         # receiver variable rebind (handled inside `Scope#with_local` / `#with_ivar`), and (2)
         # any intervening call against the same root receiver (handled by
@@ -2864,9 +2880,7 @@ module Rigor
         # - For each fact, the corresponding positional argument (matched by parameter name in
         #   the selected overload) MUST be a `Prism::LocalVariableReadNode` for narrowing to
         #   apply.
-        # - When the target is `self`, narrowing applies to the receiver — but the engine does
-        #   not yet narrow `self` itself, so `self`-targeted facts are accepted by the merger
-        #   but currently produce no scope edits.
+        # - When the target is `self`, narrowing applies to the receiver ({#apply_self_fact}).
         def analyse_rbs_extended_contribution(node, scope)
           method_def = resolve_rbs_extended_method(node, scope)
           return nil if method_def.nil?
@@ -3403,8 +3417,8 @@ module Rigor
         # extend record that is structurally incomplete: `Widget.extend(m)` at a call site and an `extend`
         # written in a file outside the analysed set are both invisible to the walk behind
         # {Scope#singleton_extends_of}, and the declaration-side record joined to it below is no more
-        # complete — RBS says nothing about a class it does not declare. A shape that turned this table into a positive
-        # `:subclass` verdict would have to be right about ABSENCE too, and it cannot be. Preserving
+        # complete — RBS says nothing about a class it does not declare. A shape that turned this table
+        # into a positive `:subclass` verdict would have to be right about ABSENCE too, and it cannot be. Preserving
         # `Singleton[C]` would also hand the arm a receiver whose singleton method table has no `clamp` on
         # it, trading the unreachable-clause false positive for an undefined-method one — the same trap
         # #657 recorded on the `Constant` carrier.
@@ -3586,7 +3600,7 @@ module Rigor
           rbs_type.is_a?(RBS::Types::Literal) && rbs_type.literal == value
         end
 
-        # The four receiver shapes with a scope binding the edges can rebind, mirroring
+        # The three receiver shapes with a scope binding the edges can rebind, mirroring
         # `apply_self_fact`. A method chain or arbitrary expression has none, so it reads nil and
         # the caller declines.
         def receiver_binding_type(receiver, scope)
@@ -3696,7 +3710,7 @@ module Rigor
 
         # Walks a call chain down to its `&.` link, collecting the suffix method names applied
         # above it (outermost first). Declines unless the chain bottoms out in a `&.` call on a
-        # direct local / ivar read — those are the two bindings a scope can rewrite — and unless
+        # direct local, instance-variable, global or constant read — the slots a scope can rewrite — and unless
         # every suffix is a bare reader or predicate, since an argument or a block could make the
         # answer depend on something other than the receiver.
         #

data/lib/rigor/inference/optimistic_origin.rb

@@ -18,7 +18,7 @@ module Rigor
     # that happens to have been produced optimistically.
     #
     # Issue #286: the `if` / `unless` branch elision is one consumer of `Narrowing.predicate_certainty`; the
-    # other two are `flow.always-truthy-condition` and the `&&` / `||` `constant_value_polarity` gate, and the
+    # other two are `flow.always-truthy-condition` and `StatementEvaluator#right_operand_dead?`, and the
     # spec passage above binds all three. This channel is what lets a certainty judgment tell the two apart.
     #
     # Issue #313: the mark is attached to a *value* — the call node that produced it, or the local / ivar it

data/lib/rigor/inference/out_buffer_mutation.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "mutation_widening"
+require_relative "receiver_alias"
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # Issue #2499 rule 3 (part of #2494) — the stdlib calls that fill a String the caller passes in. After
+    # `io.read(n, buf)`, `io.readpartial(n, buf)`, `io.sysread(n, buf)` and `io.read_nonblock(n, buf)` the buffer
+    # holds what was read, and after `StringIO.new(s)` every later write through the StringIO lands in `s`. The
+    # argument (a local, instance, class or global variable read) is widened as an in-place `replace` of it would
+    # widen it, so a `buf = +""` seed stops reading `""` after the call.
+    #
+    # A built-in catalogue keyed by method name and argument position, not a receiver-typed dispatch: a method of
+    # another class with the same name and a second positional argument loses only precision on that argument.
+    module OutBufferMutation
+      # Method name => the zero-based position of the buffer argument.
+      READERS = { read: 1, readpartial: 1, sysread: 1, read_nonblock: 1 }.freeze
+      private_constant :READERS
+
+      module_function
+
+      # `scope` with the buffer argument of `call_node` widened, or `scope` itself when the call is no such call or the
+      # argument holds no String: `Rails.cache.read(key, opts)` passes an options Hash that keeps its shape.
+      def floor(call_node, scope)
+        buffer = buffer_argument(call_node)
+        return scope if buffer.nil?
+
+        getter, = MutationWidening::ALIAS_ACCESSORS[buffer.class]
+        return scope unless string_carrier?(scope.public_send(getter, ReceiverAlias.read_name(buffer)))
+
+        MutationWidening.widen_alias_read(:replace, buffer, scope)
+      end
+
+      # A `Constant<String>` or the `String` nominal, or a union of nothing else.
+      def string_carrier?(type)
+        case type
+        when Type::Constant then type.value.is_a?(String)
+        when Type::Nominal then type.class_name == "String"
+        when Type::Union then type.members.all? { |member| string_carrier?(member) }
+        else false
+        end
+      end
+
+      def buffer_argument(call_node)
+        arguments = call_node.arguments&.arguments
+        return nil if arguments.nil?
+
+        position = READERS[call_node.name]
+        position = 0 if position.nil? && string_io_new?(call_node)
+        return nil if position.nil?
+
+        argument = arguments[position]
+        MutationWidening::ALIAS_ACCESSORS.key?(argument.class) ? argument : nil
+      end
+
+      def string_io_new?(call_node)
+        return false unless call_node.name == :new
+
+        receiver = call_node.receiver
+        case receiver
+        when Prism::ConstantReadNode then receiver.name == :StringIO
+        when Prism::ConstantPathNode then receiver.parent.nil? && receiver.name == :StringIO
+        else false
+        end
+      end
+      private_class_method :buffer_argument, :string_io_new?, :string_carrier?
+    end
+  end
+end

data/lib/rigor/inference/parameter_inference_collector.rb

@@ -95,11 +95,10 @@ module Rigor
     # may type in a later round once its own argument resolves). Unresolved call sites do not
     # contribute.
     #
-    # What it does NOT do yet (deferred — the check-wiring slice): feeding the table into the
-    # `check` walk (only `coverage --protection` consumes it today), keyword / optional / rest
-    # / block parameters, inherited-method receivers, top-level helpers, and a rigorous
-    # closed-call-site-set proof (the union is optimistic over resolved sites — acceptable
-    # because the only consumer is the protection metric, which runs no diagnostics).
+    # What it does NOT do yet: typing keyword / optional / rest / block parameters themselves,
+    # inherited-method receivers, top-level helpers, and a rigorous closed-call-site-set proof
+    # (the union is optimistic over resolved sites; the `check` walk tolerates that because an
+    # inferred parameter is only a lower bound, which the in-body rules decline on, WD6b).
     class ParameterInferenceCollector
       EMPTY = {}.freeze
 
@@ -120,7 +119,7 @@ module Rigor
       # @param files — project `.rb` paths to scan for call sites.
       # @param target_ruby — Prism parse target.
       # @param max_rounds — the WD5 fixpoint cap (1 = single-level).
-      # @return => Hash{Symbol => Rigor::Type}}] frozen.
+      # @return the inferred parameter table, frozen.
       def self.collect(files:, environment:, target_ruby: nil, max_rounds: DEFAULT_ROUNDS, workers: 0)
         new(files: files, environment: environment, target_ruby: target_ruby,
             max_rounds: max_rounds, workers: workers).collect

data/lib/rigor/inference/pre_eval_constants.rb

@@ -13,7 +13,7 @@ module Rigor
     #
     # ADR-17 slice 2 gave `pre_eval:` a project-wide **method** registry ({ProjectPatchedMethods}). A
     # constant declared in the same file stayed invisible across the file boundary: `Scope#in_source_constants`
-    # is per-file and is deliberately not part of `Runner#project_scope_seed_tables`, so only class-shaped
+    # was per-file and kept out of `Runner#project_scope_seed_tables`, so only class-shaped
     # constants (a `class` / `module` declaration, or one of the four meta-new forms `ScopeIndexer`'s
     # `record_class_new_constant_decl` promotes) ever crossed. `TIMEOUT = 30` in a listed file read as
     # `Dynamic[top]` everywhere else.

data/lib/rigor/inference/project_method_ownership.rb

@@ -2,6 +2,7 @@
 
 require_relative "../type"
 require_relative "external_ancestor_resolution"
+require_relative "../run_scoped_slots"
 
 module Rigor
   module Inference
@@ -19,7 +20,7 @@ module Rigor
       NO_TARGETS = [].freeze
       private_constant :NO_TARGETS
 
-      MEMO_KEY = :__rigor_project_method_ownership_memo__
+      MEMO_KEY = RunScopedSlots.register(:__rigor_project_method_ownership_memo__)
       private_constant :MEMO_KEY
 
       module_function
@@ -72,13 +73,15 @@ module Rigor
       # `Scope` merges each file's discovery with the project pre-pass, so the slot turns over per file, and
       # an ADR-46 dependency the first lookup recorded belongs to the file every later hit serves. Pool
       # workers are separate processes, and a Ractor has its own `Thread.current`. The `:ancestry` bucket
-      # belongs to {ClosureEscapeAnalyzer}'s ancestry step.
+      # belongs to {ClosureEscapeAnalyzer}'s ancestry step. The `:block_runs` bucket belongs to
+      # {BlockRunCount}.
       def memo(scope)
         discovery = scope.discovery
         environment = scope.environment
         slot = Thread.current[MEMO_KEY]
         unless slot && slot[0].equal?(discovery) && slot[1].equal?(environment)
-          slot = [discovery, environment, { instance: {}, singleton: {}, ancestry: {} }]
+          buckets = { instance: {}, singleton: {}, ancestry: {}, block_runs: {}.compare_by_identity }
+          slot = [discovery, environment, buckets]
           Thread.current[MEMO_KEY] = slot
         end
         slot[2]