rigortype 0.4.5 → 0.4.7

data/lib/rigor/environment.rb

@@ -16,6 +16,7 @@ require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/installed_gem_set"
 require_relative "environment/rbs_collection_discovery"
+require_relative "environment/project_path_gems"
 require_relative "environment/source_rbs_synthesis"
 require_relative "plugin/isolation"
 require_relative "cache/engine_source"
@@ -39,7 +40,7 @@ module Rigor
     DEFAULT_PROJECT_SIG_DIR = "sig"
     private_constant :DEFAULT_PROJECT_SIG_DIR
 
-    # `DEFAULT_LIBRARIES` is defined in the light `environment/default_libraries.rb` (required below) so the
+    # `DEFAULT_LIBRARIES` is defined in the light `environment/default_libraries.rb` (required above) so the
     # ADR-87 WD4 boot-slimming probe can read it without loading the inference engine.
 
     # ADR-72 — a Gemfile.lock gem name mapped to the opt-in plugin id that ships the SAME core-ext RBS. When
@@ -146,7 +147,7 @@ module Rigor
     # code (`Plugin::Registry#hkt_overlay_registry` reads each manifest); before this it sat one line ABOVE
     # the #784 rescue, so a raise there escaped {#hkt_registry} entirely. Post-#788 that is not a per-file
     # crash storm but an uncaught abort: {HktRegistryHolder#fetch} memoises only on success, so the raise
-    # is re-attempted at every demand, and the run-owned demands (`Runner::PoolCoordinator#hkt_scan_outcome`
+    # is re-attempted at every demand, and the run-owned demands (`Runner::RunLevelFacts::Collect.hkt_scan_failure`
     # after the file loop, `Analysis::WorkerSession#drain_reporters`) sit outside any rescue.
     #
     # The degradation is narrower than the scan's: only the plugin overlay is dropped, and the RBS scan
@@ -265,10 +266,12 @@ module Rigor
       #   `nil` (the default), the canonical project layout `<root>/sig` is used if it exists, otherwise no
       #   signature path is loaded.
       # @param cache_store — persistent cache threaded into the underlying
-      #   {Environment::RbsLoader} so constant lookups (and, in later v0.0.9 slices, other reflection
-      #   artefacts) consult the cache. Pass `nil` (the default) to skip caching for this environment.
+      #   {Environment::RbsLoader} so constant lookups consult the cache. Pass `nil` (the default) to skip
+      #   caching for this environment.
+      # @param core_root — issue #2517 — a core signature directory loaded in place of the `rbs` gem's `core/`
+      #   ({Configuration#core_root}); nil (the default) loads the gem's core.
       # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
-      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil,
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil, # rubocop:disable Metrics/AbcSize
                       plugin_registry: nil, dependency_source_index: nil,
                       rbs_extended_reporter: nil, boundary_cross_reporter: nil,
                       source_rbs_synthesis_reporter: nil,
@@ -276,7 +279,8 @@ module Rigor
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
                       synthetic_method_index: nil, project_patched_methods: nil,
-                      source_files: [], locked_gems: nil, required_features: nil)
+                      source_files: [], locked_gems: nil, required_features: nil, core_root: nil,
+                      paths: nil, exclude_patterns: nil, exclude_base: nil)
         resolved_paths = project_signature_roots(signature_paths, root: root)
         # O4 MVP — append per-gem `sig/` directories discovered under the target project's bundler install
         # root. Empty array when neither an explicit path nor auto-detection finds a bundle. Order: user
@@ -318,7 +322,11 @@ module Rigor
         # Issue #1700 — plus the gated vendored directories this run's source activates ({#feature_tokens}).
         merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s) +
                             feature_tokens(required_features, source_files, libraries)).uniq
-        skip_gem_names = collection_skip_gem_names(merged_libraries)
+        # Issue #2441 — plus the project's own path gems ({ProjectPathGems}), whose collection copy would
+        # double-declare the project's `sig/`.
+        project_gems = ProjectPathGems.names(locked, paths: paths, root: root, exclude_patterns: exclude_patterns,
+                                                     exclude_base: exclude_base || root)
+        skip_gem_names = collection_skip_gem_names(merged_libraries) + project_gems.to_a
         collection_paths = RbsCollectionDiscovery.discover(
           lockfile_path: rbs_collection_lockfile,
           project_root: root,
@@ -338,8 +346,10 @@ module Rigor
         # opt-in plugin twin is REACHABLE — loaded as a plugin, or wired in by `signature_paths:` (#672) —
         # so the two never both declare the methods. The paths ride in `loader_signature_paths`, so the env
         # cache descriptor digests them for free.
+        # Issue #2441 — the project's own path gems are neither missing RBS nor overlay-eligible: the project's
+        # `sig/` declares them, and an overlay (`data/gem_overlay/activesupport`) would collide with it.
         missing_gems, overlay_paths = missing_gems_and_overlay_paths(
-          locked: locked, default_libraries: merged_libraries, bundle_sig_paths: gem_sig_paths,
+          locked: locked.except(*project_gems), default_libraries: merged_libraries, bundle_sig_paths: gem_sig_paths,
           rbs_collection_paths: collection_paths, plugin_registry: plugin_registry,
           signature_paths: resolved_paths, bundle_root: bundle_root
         )
@@ -364,7 +374,10 @@ module Rigor
           # Issue #610 — the plugin-contributed subset is loaded LAST and may stand down against a colliding
           # generic arity. Only the bundled plugins' own `sig/` is deferred: the user's `signature_paths:`,
           # the bundle walk and `rbs collection install` all stay authoritative.
-          deferred_signature_paths: plugin_sig_paths
+          deferred_signature_paths: plugin_sig_paths,
+          project_signature_paths: resolved_paths,
+          required_features: required_features || RequiredFeatures.scan(source_files, sig_paths: resolved_paths),
+          core_root: core_root
         )
         # Issues #824 / #1075 — the rows ADR-112 WD5's consistency rule reports for members the project's
         # own `sig/` and an inline source both declare: an error per contradiction (or per refinement that
@@ -374,6 +387,10 @@ module Rigor
         # on every run, so the member-level outcome needs no plumbing of its own. Costs nothing for a project
         # with no inline RBS: the loader's reader short-circuits on an empty `virtual_rbs`.
         record_member_consistency(loader, source_rbs_synthesis_reporter, root)
+        # Issue #2517 — a selected core is built here, not lazily. The env is first demanded from inside a file's
+        # analysis, under rescues that turn any raise into one `internal analyzer error` row per file; building it
+        # now raises the {CoreRootError} once, before analysis, where the CLI reports it as a configuration error.
+        loader.verify_core_root!
         # ADR-20 slice 2c + 2e — seed hkt_registry with the bundled builtins. The Environment's
         # `#hkt_registry` getter then LAZILY merges in the RBS env scan on first call so fast paths that
         # don't consult HKT (e.g. `rigor check --cache-stats --no-stats`) don't pay the eager env-build cost
@@ -490,7 +507,7 @@ module Rigor
       end
 
       # ADR-72 — resolve the bundled RBS overlay directories to load for this project. A gem is eligible when
-      # it is classified `:missing` (see {missing_rbs_gem_rows}) and its conflicting opt-in plugin twin (if
+      # it is classified `:missing` (see {missing_rows}) and its conflicting opt-in plugin twin (if
       # any) is NOT already reachable. Returns `[Pathname]`, deterministically ordered, or `[]` when no
       # eligible gem.
       #
@@ -642,6 +659,8 @@ module Rigor
       def record_member_undecided(reporter, record, root)
         plugin_id, path = split_virtual_source_name(record.virtual_name)
         return if path.nil?
+        return record_variable_undecided(reporter, record, root, plugin_id, path) if
+          MemberConsistency.variable_kind?(record.kind)
 
         reporter.record(
           plugin_id: plugin_id, path: path, kind: :not_honoured,
@@ -654,8 +673,22 @@ module Rigor
         )
       end
 
+      # Issue #2440 — an instance variable declared by both sides with different types. `sig/` binds
+      # (the coordinator's ruling on #2440, ADR-5): the row is `:info`, never `rbs.contradicting-signature`.
+      def record_variable_undecided(reporter, record, root, plugin_id, path)
+        reporter.record(
+          plugin_id: plugin_id, path: path, kind: :not_honoured,
+          message: "`#{member_label(record)}` is also declared in " \
+                   "`#{path_relative_to(record.signature_path, root)}` with a different type " \
+                   "(#{record.detail}), so the `.rbs` declaration binds and the inline one was dropped. " \
+                   "RBS rejects two declarations of one instance variable, so only one can stay; " \
+                   "regenerate the committed `.rbs` (`rbs-inline --output`) or align the two types."
+        )
+      end
+
+      # `Demo#m` / `Demo.m` for a method, `Demo#@x` / `Demo.@x` for an instance / class instance variable.
       def member_label(record)
-        separator = record.kind == :singleton ? "." : "#"
+        separator = %i[singleton class_instance_variable].include?(record.kind) ? "." : "#"
         "#{record.class_name}#{separator}#{record.method_name}"
       end
 

data/lib/rigor/flow_contribution/merger.rb

@@ -26,13 +26,13 @@ module Rigor
     #
     # ## Composition rules (ADR-2)
     #
-    # - `:return_type` — Intersect via `Type::Combinator.intersection`; collapse to bot raises
-    #   `:return_type_collapse`.
+    # - `:return_type` — Intersect via `Type::Combinator.intersection`; collapse to bot records a
+    #   `:return_type_collapse` conflict.
     # - `:truthy_fact` / `:falsey_fact` / `:post_return_fact` — Edge-local; accumulate while deduping by
     #   payload equality.
     # - `:mutation` / `:invalidation` / `:role` — Union; dedupe by equality.
-    # - `:exception` — Single-valued. Two non-`nil` non-equal exceptional effects raise
-    #   `:exceptional_disagreement`.
+    # - `:exception` — Single-valued. Two non-`nil` non-equal exceptional effects record an
+    #   `:exceptional_disagreement` conflict.
     #
     # ## Cross-tier contradictions
     #

data/lib/rigor/inference/acceptance.rb

@@ -75,41 +75,66 @@ module Rigor
       }.freeze
       private_constant :TYPE_HANDLERS
 
-      UNREAD_HASH_REFUSED_KEY = :__rigor_acceptance_unread_hash_refused__
-      private_constant :UNREAD_HASH_REFUSED_KEY
-
-      # Whether a `maybe` for `param` against `arg` rests on a record that could not read a hash's entries: a
-      # `Hash` with a gradual arm ({#gradual_hash?}) or an open `HashShape`. The record cannot prove the key set
-      # of either, and its `maybe` climbs through whatever holds the record. `OverloadSelector`'s strict pass
-      # reads that `maybe` as no evidence for the overload, so this re-asks with each such record answering
-      # `no` and reports whether the pair then fails. A `maybe` from anywhere else (a subclass only the Ruby
-      # source declares, a splat under a parameter that is no record) survives the re-ask and still counts.
-      def maybe_rests_on_unread_hash?(param, arg)
-        return false unless contains_type?(param) { |type| type.is_a?(Type::HashShape) }
-        return false unless contains_type?(arg) { |type| unread_hash?(type) }
-
-        refusing_unread_hashes { accepts(param, arg, mode: :gradual).no? }
+      UNREAD_SHAPE_REFUSED_KEY = :__rigor_acceptance_unread_shape_refused__
+      private_constant :UNREAD_SHAPE_REFUSED_KEY
+
+      # Whether a `maybe` for `param` against `arg` rests on a shape that could not read its argument: a record
+      # against a `Hash` with a gradual arm ({#gradual_hash?}) or an open `HashShape`, or a tuple against an
+      # `Array` of unknown arity ({#array_carrier?}). The shape cannot prove the key set or the length, and its
+      # `maybe` climbs through whatever holds it. `OverloadSelector`'s strict pass reads that `maybe` as no
+      # evidence for the overload, so this re-asks with each such shape answering `no` and reports whether the
+      # pair then fails. A `maybe` from anywhere else (a subclass only the Ruby source declares, a splat under a
+      # parameter that is no shape) survives the re-ask and still counts.
+      def maybe_rests_on_unread_shape?(param, arg)
+        return false unless rests_on_unread_hash?(param, arg) || rests_on_unread_array?(param, arg)
+
+        refusing_unread(:all) { accepts(param, arg, mode: :gradual).no? }
       end
 
+      # Whether any of `types` holds an `Array` a tuple cannot read ({#array_carrier?}), so a match may rest on
+      # the tuple's `maybe`. `OverloadSelector`'s gradual pass asks before re-matching under
+      # {#refusing_unread_arrays}.
+      def unread_array_in?(types)
+        types.any? { |type| contains_type?(type) { |inner| array_carrier?(inner) } }
+      end
+
+      # Runs the block with each tuple answering `no`, not `maybe`, for an `Array` of unknown arity. A record's
+      # `maybe` for an unread hash is untouched.
+      def refusing_unread_arrays(&) = refusing_unread(:array, &)
+
       # rubocop:disable-next Metrics/ClassLength
       class << self
         private
 
-        # The flag lives on the thread, not on a parameter, because the record may sit any number of `accepts`
+        def rests_on_unread_hash?(param, arg)
+          contains_type?(param) { |type| type.is_a?(Type::HashShape) } &&
+            contains_type?(arg) { |type| unread_hash?(type) }
+        end
+
+        def rests_on_unread_array?(param, arg)
+          contains_type?(param) { |type| type.is_a?(Type::Tuple) } &&
+            contains_type?(arg) { |type| array_carrier?(type) }
+        end
+
+        # The flag lives on the thread, not on a parameter, because the shape may sit any number of `accepts`
         # calls below the one asked (a tuple element, a `Hash` value, a union member), and those calls go
-        # through each carrier's `Type#accepts`. It is set only for the duration of the block.
-        def refusing_unread_hashes
-          previous = Thread.current[UNREAD_HASH_REFUSED_KEY]
-          Thread.current[UNREAD_HASH_REFUSED_KEY] = true
+        # through each carrier's `Type#accepts`. It is set only for the duration of the block. `kind` is `:all`
+        # (records and tuples) or `:array` (tuples only).
+        def refusing_unread(kind)
+          previous = Thread.current[UNREAD_SHAPE_REFUSED_KEY]
+          Thread.current[UNREAD_SHAPE_REFUSED_KEY] = kind
           yield
         ensure
-          Thread.current[UNREAD_HASH_REFUSED_KEY] = previous
+          Thread.current[UNREAD_SHAPE_REFUSED_KEY] = previous
         end
 
-        # The `maybe` a record answers for a hash whose entries it cannot read, or `no` inside
-        # {#refusing_unread_hashes}.
-        def unread_hash_maybe(mode, reason)
-          return hash_shape_no(mode, "#{reason} (refused as evidence)") if Thread.current[UNREAD_HASH_REFUSED_KEY]
+        # The `maybe` a shape of `kind` (`:hash` or `:array`) answers for an argument it cannot read, or `no`
+        # inside {#refusing_unread} for that kind.
+        def unread_shape_maybe(mode, reason, kind)
+          refused = Thread.current[UNREAD_SHAPE_REFUSED_KEY]
+          if refused == :all || refused == kind
+            return Type::AcceptsResult.no(mode: mode, reasons: "#{reason} (refused as evidence)")
+          end
 
           Type::AcceptsResult.maybe(mode: mode, reasons: reason)
         end
@@ -469,9 +494,10 @@ module Rigor
         end
 
         # Returns `other_type` rewritten so its type_args have the same arity as `self_type.type_args`, or
-        # `nil` if no projection is known. Today only the Hash → Enumerable projection is hand-rolled; a
-        # general RBS-driven implementation that consults `definition.ancestors[i].args` for arbitrary
-        # subclass / module-include relations is the principled follow-up.
+        # `nil` if no projection is known. Today the Hash → Enumerable and ArithmeticSequence → Enumerator
+        # projections are hand-rolled; a general RBS-driven implementation that consults
+        # `definition.ancestors[i].args` for arbitrary subclass / module-include relations is the principled
+        # follow-up.
         def project_to_target_arity(self_type, other_type)
           return nil if self_type.type_args.size == other_type.type_args.size
           return nil if self_type.type_args.empty? || other_type.type_args.empty?
@@ -881,8 +907,8 @@ module Rigor
         # `Refined[base, predicate]` accepts another type X when the base accepts the *base* of X *and* X is
         # provably contained in the predicate's value set. The base check is delegated to
         # `accepts(self.base, X.base)` so handlers like `accepts_nominal` see Nominal-vs-Nominal and return
-        # their normal answer (the inner `accepts_nominal` does not register `Refined` / `Difference` as
-        # direct other-shapes — projecting to the base is what makes the comparison meaningful).
+        # their normal answer (`accepts_nominal` projects a `Refined` / `Difference` other onto its base,
+        # which is what makes the comparison meaningful).
         #
         # Provability rules in gradual mode (the conservative analogue of `accepts_difference`):
         #
@@ -1003,9 +1029,12 @@ module Rigor
 
         # Tuple[A1..An] accepts:
         # - Tuple[B1..Bn] when arities match and each Ai accepts Bi (covariant per-position).
-        # - Anything else: no (we cannot prove the arity from a generic nominal alone).
+        # - An `Array[E]` (see {#array_element_verdict}): maybe, or no on an element contradiction.
+        # - Anything else: no.
         def accepts_tuple(self_type, other_type, mode)
           unless other_type.is_a?(Type::Tuple)
+            return array_element_verdict(self_type, other_type, mode) if array_carrier?(other_type)
+
             return Type::AcceptsResult.no(
               mode: mode,
               reasons: "Tuple does not accept #{other_type.class}"
@@ -1025,6 +1054,38 @@ module Rigor
           combine_arg_results(per_element, mode)
         end
 
+        # An `Array` nominal, directly or as the base of a `Difference` (`non-empty-array[E]`). Its arity is
+        # unknown, so a tuple cannot reject it on length: `URI.encode_www_form` takes
+        # `Enumerable[[_ToS, _ToS]]` and is handed the `Array[Array[String]]` that `URI.decode_www_form`
+        # answers. An `Array` subclass is not read, as {#gradual_hash?} does not read a `Hash` subclass.
+        def array_carrier?(type)
+          nominal = type.is_a?(Type::Difference) ? type.base : type
+          nominal.is_a?(Type::Nominal) && nominal.class_name == "Array"
+        end
+
+        # `maybe`, unless the element type rules the tuple out at any length: some position accepts no member
+        # of `E` (`[Integer, Integer]` never takes an `Array[String]`). A raw `Array` stays `maybe`, and so does
+        # an element with a gradual arm, since no position rejects a `Dynamic` member. The accepted cost (ADR-5)
+        # is that a wrong-length `Array[E]` passed or returned where a tuple is declared goes unreported.
+        def array_element_verdict(self_type, other_type, mode)
+          nominal = other_type.is_a?(Type::Difference) ? other_type.base : other_type
+          element = nominal.type_args.first
+          unless element.nil?
+            members = ContentJoin.union_members(element)
+            refused = self_type.elements.find do |formal|
+              members.all? { |member| accepts(formal, member, mode: mode).no? }
+            end
+            if refused
+              return Type::AcceptsResult.no(
+                mode: mode,
+                reasons: "tuple member #{refused.describe(:short)} rejects #{element.describe(:short)}"
+              )
+            end
+          end
+
+          unread_shape_maybe(mode, "tuple arity unknown for #{other_type.describe(:short)}", :array)
+        end
+
         # HashShape{k1: T1, ...} accepts another HashShape when every required key of self is required on
         # the other side and Ti accepts Ui (depth covariant). Optional keys may be absent on the other side;
         # when present, their values are checked. A closed self rejects known extra keys, and answers at most
@@ -1056,7 +1117,7 @@ module Rigor
           result = combine_arg_results(per_entry, mode)
           return result unless result.yes? && self_type.closed? && other_type.open?
 
-          unread_hash_maybe(mode, "HashShape closed target cannot check open source")
+          unread_shape_maybe(mode, "HashShape closed target cannot check open source", :hash)
         end
 
         # A `Hash` nominal — directly or as the base of a `Difference` (`non-empty-hash[K, V]`) — that is raw or
@@ -1085,7 +1146,7 @@ module Rigor
           refused = refused_value_keys(self_type, value_type, mode)
           return hash_shape_no(mode, "Hash value type refused for required keys: #{refused.inspect}") if refused.any?
 
-          unread_hash_maybe(mode, "HashShape cannot check #{other_type.describe(:short)}")
+          unread_shape_maybe(mode, "HashShape cannot check #{other_type.describe(:short)}", :hash)
         end
 
         def unholdable_keys(self_type, key_type, mode)

data/lib/rigor/inference/block_parameter_binder.rb

@@ -211,9 +211,8 @@ module Rigor
         cursor
       end
 
-      # `|*rest|` binds an Array of the leftover positional arguments. The expected-types array is
-      # per-position, not per-rest; we cannot reliably pick a single element type for rest, so we default to
-      # `Array[Dynamic[Top]]`. Element-type precision for rest parameters is deferred (demand-gated).
+      # `|*rest|` binds an Array of the leftover positional arguments: `Array[Dynamic[Top]]`, unless an
+      # auto-splat answered a rest type ({BlockAutoSplat}). The expected types are per-position, not per-rest.
       def bind_rest(params_node, bindings)
         rest = params_node.rest
         return unless rest.respond_to?(:name) && rest&.name

data/lib/rigor/inference/block_run_count.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "block_call_timing"
+require_relative "closure_escape_analyzer"
+require_relative "project_method_ownership"
+
+module Rigor
+  module Inference
+    # Issue #2303 — whether a project method's body may run the block it is called with more than once ON ONE PATH,
+    # for the expression-position block-value pass (`ExpressionTyper#block_may_repeat?` through
+    # {ProjectYielder.block_value_may_repeat?}). That pass lays the #587 (b) captured binding under a repeating block,
+    # which adds values a single run never reads, so a callee read as repeating when it is not reports diagnostics on
+    # correct code (`s = "a"; r = either(f) { t = s; s = nil; t }; r.upcase`). The rule here therefore errs toward
+    # "runs once", unlike {ProjectYielder.may_run_block_repeatedly?}, whose only asker widens a return type.
+    #
+    # The walk counts block runs per path, saturating at {MANY}:
+    #
+    # - a `yield`, or `call` / `yield` / `===` / `[]` on the `&blk` parameter, is one run;
+    # - a sequence sums, and a branch (`if` / `unless` / ternary / `case` / `case ... in`) takes the largest arm,
+    #   so `f ? yield(1) : yield(2)` is one run;
+    # - a `return`, `break`, `next` or receiver-less `raise` / `fail` ends its path, so the `yield` after
+    #   `return yield(1) if k` is a different path from the one before it;
+    # - the body of `while` / `until` / `for`, of `Kernel#loop`, or the block of a catalogued core iterator
+    #   ({ClosureEscapeAnalyzer.iterator_name?}) is {MANY} when a run lies on a path that reaches the next
+    #   iteration (falling through the body, or a `next`); a run only on a path that leaves it (`return`, `break`,
+    #   `raise`) adds what that path holds, so `xs.each { |x| return yield(x) if x > 1 }` is one run;
+    # - a hand-off of the block (`g(&blk)`, `g(&)`, `...`) is {MANY};
+    # - a block under any other call runs its body once (`then { yield }`, `synchronize { yield }`,
+    #   `File.open(f) { yield f }`), a lambda body is not run at its definition, and a nested `def` is not this
+    #   method's body.
+    #
+    # Reading `&blk` other than calling it (`return unless blk`) is no run.
+    #
+    # A result is `[fall, total, nxt, brk]`: the most runs on a path that falls through the node, on any path
+    # through it, on a path that ends at a `next`, and on one that ends at a `break` (nil where no path does).
+    module BlockRunCount
+      module_function
+
+      MANY = 2
+      ZERO = [0, 0, nil, nil].freeze
+      ALWAYS = [MANY, MANY, nil, nil].freeze
+      BLOCK_RUN_CALLS = Set[:call, :yield, :===, :[]].freeze
+      LOOP_NODES = [Prism::WhileNode, Prism::UntilNode, Prism::ForNode].freeze
+      RAISING_CALLS = Set[:raise, :fail].freeze
+      private_constant :ZERO, :ALWAYS, :BLOCK_RUN_CALLS, :LOOP_NODES, :RAISING_CALLS
+
+      # Memoised per `def` node for the run ({ProjectMethodOwnership.memo}): every call site, and every pass over
+      # one, asks the same callee.
+      def may_repeat?(def_node, scope)
+        memo = ProjectMethodOwnership.memo(scope)[:block_runs]
+        return memo[def_node] if memo.key?(def_node)
+
+        memo[def_node] = runs(def_node.body, def_node.parameters&.block&.name)[1] >= MANY
+      end
+
+      def runs(node, block_name)
+        case node
+        when nil, Prism::DefNode, Prism::LambdaNode then ZERO
+        when Prism::YieldNode then run_after(sequence(node.compact_child_nodes, block_name))
+        when Prism::ForwardingArgumentsNode then ALWAYS
+        when Prism::BlockArgumentNode then block_argument_runs(node, block_name)
+        when Prism::IfNode then branch(runs(node.predicate, block_name), [node.statements, node.subsequent], block_name)
+        when Prism::UnlessNode
+          branch(runs(node.predicate, block_name), [node.statements, node.else_clause], block_name)
+        when Prism::CaseNode, Prism::CaseMatchNode then case_runs(node, block_name)
+        when Prism::CallNode then call_runs(node, block_name)
+        else other_runs(node, block_name)
+        end
+      end
+
+      def other_runs(node, block_name)
+        result = sequence(node.compact_child_nodes, block_name)
+        case node
+        when *LOOP_NODES then iterated(result)
+        when Prism::ReturnNode then [nil, result[1], result[2], result[3]]
+        when Prism::NextNode then [nil, result[1], larger(result[2], result[0]), result[3]]
+        when Prism::BreakNode then [nil, result[1], result[2], larger(result[3], result[0])]
+        else result
+        end
+      end
+
+      # A body run any number of times: {MANY} when a run reaches the next iteration, else the runs of the paths
+      # that leave it. It may run zero times or be left by a `break`, and the walk continues after it either way.
+      def iterated((fall, total, nxt, brk))
+        again = [fall, nxt].compact.max || 0
+        return ALWAYS if again.positive?
+
+        [[0, brk].compact.max, total, nil, nil]
+      end
+
+      # A body run once: a `next` or `break` in it ends the run, and the walk continues after the call.
+      def run_once((fall, total, nxt, brk))
+        [[fall, nxt, brk].compact.max, total, nil, nil]
+      end
+
+      def block_argument_runs(node, block_name)
+        expression = node.expression
+        forwards = expression.nil? || (expression.is_a?(Prism::LocalVariableReadNode) && expression.name == block_name)
+        forwards ? ALWAYS : runs(expression, block_name)
+      end
+
+      def sequence(nodes, block_name)
+        nodes.reduce(ZERO) do |acc, child|
+          break acc if acc[0].nil?
+
+          chain(acc, runs(child, block_name))
+        end
+      end
+
+      # `first` then `second`; nothing follows a path that does not fall through `first`.
+      def chain(first, second)
+        fall, total, nxt, brk = first
+        return first if fall.nil?
+
+        [second[0] && sum(fall, second[0]), [total, sum(fall, second[1])].max,
+         larger(nxt, second[2] && sum(fall, second[2])), larger(brk, second[3] && sum(fall, second[3]))]
+      end
+
+      def run_after(result)
+        chain(result, [1, 1, nil, nil])
+      end
+
+      # `head` runs first, then exactly one of `arms` (a nil arm is the path that takes none).
+      def branch(head, arms, block_name)
+        return head if head[0].nil?
+
+        arms.map { |arm| chain(head, runs(arm, block_name)) }.reduce do |a, b|
+          [larger(a[0], b[0]), [a[1], b[1]].max, larger(a[2], b[2]), larger(a[3], b[3])]
+        end
+      end
+
+      def case_runs(node, block_name)
+        clauses = node.conditions
+        tests = clauses.flat_map { |clause| clause.is_a?(Prism::WhenNode) ? clause.conditions : [clause.pattern] }
+        arms = clauses.map(&:statements) + [node.else_clause]
+        branch(sequence([node.predicate, *tests], block_name), arms, block_name)
+      end
+
+      def call_runs(node, block_name)
+        return run_after(runs(node.arguments, block_name)) if block_run_call?(node, block_name)
+
+        block = node.block
+        literal = block.is_a?(Prism::BlockNode)
+        head = sequence([node.receiver, node.arguments, (block unless literal)], block_name)
+        return [nil, head[1], head[2], head[3]] if raising_call?(node)
+        return head unless literal
+
+        body = runs(block.body, block_name)
+        chain(head, repeating_call?(node) ? iterated(body) : run_once(body))
+      end
+
+      def sum(left, right)
+        (left + right).clamp(0, MANY)
+      end
+
+      def larger(left, right)
+        [left, right].compact.max
+      end
+
+      def repeating_call?(node)
+        ClosureEscapeAnalyzer.iterator_name?(node.name) || BlockCallTiming.kernel_loop?(node)
+      end
+
+      def raising_call?(node)
+        node.receiver.nil? && RAISING_CALLS.include?(node.name)
+      end
+
+      # `blk.call` and its spellings.
+      def block_run_call?(node, block_name)
+        receiver = node.receiver
+        !block_name.nil? && receiver.is_a?(Prism::LocalVariableReadNode) && receiver.name == block_name &&
+          BLOCK_RUN_CALLS.include?(node.name)
+      end
+    end
+  end
+end

data/lib/rigor/inference/budget_trace.rb

@@ -16,7 +16,7 @@ module Rigor
     # non-stores) vs memo-key normalization (collapse arg-granularity thrash — a signature whose distinct-key
     # count far exceeds its body-eval savings).
     #
-    # Three categories, one per guard site:
+    # The cutoff categories, one per guard site:
     #
     # - {RECURSION_GUARD} — `ExpressionTyper#infer_user_method_return` detected a `(receiver, method)` cycle
     #   and returned `Dynamic[top]` (the de-facto recursion-depth budget, effective depth 1).
@@ -27,6 +27,8 @@ module Rigor
     #   fuel and fell back to the plain `(receiver, method)` guard (in-cycle call → `Dynamic[top]`).
     # - {RECURSION_FIXPOINT_CAP} — the fixpoint return-summary iteration (ADR-55 slice 2) hit its 3-evaluation
     #   cap without converging and collapsed the summary to `untyped` (today's behaviour).
+    # - {BLOCK_WRITEBACK_CAP} — the block / loop write-back fixpoint ({BodyFixpoint.converge}) collapsed a
+    #   local that had not converged to `Dynamic[top]`.
     #
     # Enabled only when `RIGOR_BUDGET_TRACE` is set (to any non-empty value) in the environment, or via
     # {enable!} in tests. When disabled, {hit} is a single boolean check and returns immediately, so normal
@@ -52,6 +54,10 @@ module Rigor
       # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint and by slice C's
       # content-evidence fixpoint, where the collapsed name is one element / key / value slot of a collection join.
       BLOCK_WRITEBACK_CAP = :block_writeback_cap
+      # `CalleeMutationChain` discovered more than {CalleeMutationChain::MAX_NODES} nodes from one parameter and took
+      # the rest as mutating (the callee floor's FP-safe cut). A label: it may vary with the order, the floor does not
+      # (ADR-127).
+      CALLEE_CHAIN_CAP = :callee_chain_cap
 
       # ADR-57 return-memo profile counters (not cutoffs — see the module doc). All bumped by
       # `ExpressionTyper#infer_user_method_return` / `#compute_user_method_return`.
@@ -82,7 +88,7 @@ module Rigor
 
       CATEGORIES = [
         RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED, RECURSION_UNROLL_FUEL,
-        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP,
+        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP, CALLEE_CHAIN_CAP,
         MEMO_ENTRIES, MEMO_HITS, MEMO_MISSES, MEMO_BODY_EVALS,
         MEMO_REFUSE_ON_STACK, MEMO_REFUSE_UNROLL, MEMO_REFUSE_TRANSIENT
       ].freeze

data/lib/rigor/inference/builtins/exception_catalog.rb

@@ -9,8 +9,8 @@ module Rigor
       #
       # Exception is the base of every Ruby error class (RuntimeError, StandardError, KeyError, …). The
       # Init_Exception block in `references/ruby/error.c` registers the entire hierarchy in one pass, so
-      # the YAML carries 27 classes — but only the base `Exception` row is wired into `CATALOG_BY_CLASS`
-      # for v0.0.5. A `RuntimeError` receiver hits the Exception arm via `is_a?(Exception)` and the
+      # the YAML carries 27 classes — but only the base `Exception` row is wired into `CATALOG_BY_CLASS`.
+      # A `RuntimeError` receiver hits the Exception arm via `is_a?(Exception)` and the
       # catalog answers with the base-class entries; subclass-specific methods (`KeyError#receiver`,
       # `NameError#name`, …) intentionally miss the lookup until a later slice routes per-subclass
       # class_names.

data/lib/rigor/inference/builtins/numeric_catalog.rb

@@ -16,11 +16,8 @@ module Rigor
       #
       # No mutation blocklist is needed. The numeric classes expose no foldable bang or indirect-mutator
       # method that the static C classifier mis-attributes (every `:leaf` numeric method is a pure value
-      # computation), so the generic `MethodCatalog` loader — shared with the eighteen other per-class
-      # catalogs — covers it directly. This previously hand-rolled its own `safe_for_folding?` /
-      # `method_entry` / `load_catalog` copy of `MethodCatalog`; folding it onto the shared loader also
-      # picks up alias resolution (e.g. `Integer#magnitude` → `abs`, `Integer#inspect` → `to_s`), which the
-      # old bespoke loader silently dropped.
+      # computation), so the generic `MethodCatalog` loader covers it directly. Using the shared loader
+      # rather than a bespoke copy also gives it alias resolution (e.g. `Integer#magnitude` → `abs`).
       NUMERIC_CATALOG = MethodCatalog.for_topic("numeric")
     end
   end

data/lib/rigor/inference/builtins/random_catalog.rb

@@ -20,8 +20,8 @@ module Rigor
         mutating_selectors: {
           "Random" => Set[
             # `rand_random` -> `random_real` / `random_ulong_limited` advance the MT state on the receiver
-            # (instance #rand) and on `Random::DEFAULT` (singleton .rand). The classifier misses the
-            # indirect mutator.
+            # (instance #rand) and on the process-wide default generator (singleton .rand). The classifier
+            # misses the indirect mutator.
             :rand,
             # `random_bytes` / `random_s_bytes` consume MT output the same way #rand does — every call
             # mutates the underlying generator.