rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/block_parameter_binder.rb

@@ -7,62 +7,45 @@ require_relative "multi_target_binder"
 
 module Rigor
   module Inference
-    # Builds the entry scope of a block body by translating the block's
-    # parameter list into a `name -> Rigor::Type` map.
+    # Builds the entry scope of a block body by translating the block's parameter list into a `name ->
+    # Rigor::Type` map.
     #
-    # The binder is the symmetric counterpart of {MethodParameterBinder}
-    # for `Prism::BlockNode`. The expected parameter types come from
-    # the receiving method's RBS signature
-    # ({Rigor::Inference::MethodDispatcher.expected_block_param_types});
-    # parameters that the signature does not cover (or that the binder
-    # cannot match by position) default to `Dynamic[Top]`. The default
-    # is the Slice 1 fail-soft answer for unknown values, so a block
-    # whose receiving method has no signature still binds every name
-    # into the scope (a block body whose `Local x` reads return
-    # `Dynamic[Top]` instead of falling through to the unbound-local
-    # `Dynamic[Top]` event is the same observable type, but the
-    # binding presence is what later slices need to attach narrowing
-    # facts to).
+    # The binder is the symmetric counterpart of {MethodParameterBinder} for `Prism::BlockNode`. The
+    # expected parameter types come from the receiving method's RBS signature
+    # ({Rigor::Inference::MethodDispatcher.expected_block_param_types}); parameters that the signature does
+    # not cover (or that the binder cannot match by position) default to `Dynamic[Top]`. The default is the
+    # Slice 1 fail-soft answer for unknown values, so a block whose receiving method has no signature still
+    # binds every name into the scope (a block body whose `Local x` reads return `Dynamic[Top]` instead of
+    # falling through to the unbound-local `Dynamic[Top]` event is the same observable type, but the binding
+    # presence is what later slices need to attach narrowing facts to).
     #
-    # MultiTargetNode parameters (`|(a, b), c|`) are bound by
-    # delegating each destructuring slot to
-    # {Rigor::Inference::MultiTargetBinder}, so a Tuple-shaped
-    # expected element type projects element-wise into the inner
-    # locals (Slice 6 phase C sub-phase 2). Numbered parameters
-    # (`_1`, `_2`, ...) are bound from `Prism::NumberedParametersNode`
-    # using the same per-position `expected_param_types:` array, so
-    # `[1, 2, 3].each { _1 + _2 }` sees `_1`/`_2` typed identically
-    # to their explicit `|x, y|` counterparts.
+    # MultiTargetNode parameters (`|(a, b), c|`) are bound by delegating each destructuring slot to
+    # {Rigor::Inference::MultiTargetBinder}, so a Tuple-shaped expected element type projects element-wise
+    # into the inner locals (Slice 6 phase C sub-phase 2). Numbered parameters (`_1`, `_2`, ...) are bound
+    # from `Prism::NumberedParametersNode` using the same per-position `expected_param_types:` array, so
+    # `[1, 2, 3].each { _1 + _2 }` sees `_1`/`_2` typed identically to their explicit `|x, y|` counterparts.
     #
-    # The `it` implicit parameter (Ruby 3.4+) is bound from
-    # `Prism::ItParametersNode`. It is the single-argument cousin of
-    # `_1`: the binder produces `{ it: expected_param_types[0] }` so
-    # the body's `Prism::ItLocalVariableReadNode` lookup sees the same
-    # type as the explicit `|x|` form would.
+    # The `it` implicit parameter (Ruby 3.4+) is bound from `Prism::ItParametersNode`. It is the
+    # single-argument cousin of `_1`: the binder produces `{ it: expected_param_types[0] }` so the body's
+    # `Prism::ItLocalVariableReadNode` lookup sees the same type as the explicit `|x|` form would.
     #
-    # Block-local declarations after `;` (e.g., `|x; y, z|`) are
-    # still skipped — they are explicitly block-local, so the outer
-    # scope MUST NOT observe them and the binder leaves them unbound.
+    # Block-local declarations after `;` (e.g., `|x; y, z|`) are still skipped — they are explicitly
+    # block-local, so the outer scope MUST NOT observe them and the binder leaves them unbound.
     #
     # See docs/internal-spec/inference-engine.md for the binding contract.
     class BlockParameterBinder
-      # @param expected_param_types [Array<Rigor::Type>] positional block
-      #   parameter types in order. Indices the binder cannot fill from
-      #   this array (because the array is shorter than the parameter
-      #   list, or because the slot is a kind we do not pull from the
-      #   array) default to `Dynamic[Top]`.
+      # @param expected_param_types [Array<Rigor::Type>] positional block parameter types in order. Indices
+      #   the binder cannot fill from this array (because the array is shorter than the parameter list, or
+      #   because the slot is a kind we do not pull from the array) default to `Dynamic[Top]`.
       def initialize(expected_param_types: [])
         @expected_param_types = expected_param_types
       end
 
       # @param block_node [Prism::BlockNode]
-      # @return [Hash{Symbol => Rigor::Type}] ordered map from parameter
-      #   name to bound type. Anonymous parameters are skipped;
-      #   MultiTargetNode destructuring slots delegate to
-      #   {MultiTargetBinder} and contribute every named local in
-      #   declaration order. Numbered-parameter forms (`_1`, `_2`,
-      #   ...) bind `:_1`, `:_2`, ... up to the maximum the block
-      #   body refers to.
+      # @return [Hash{Symbol => Rigor::Type}] ordered map from parameter name to bound type. Anonymous
+      #   parameters are skipped; MultiTargetNode destructuring slots delegate to {MultiTargetBinder} and
+      #   contribute every named local in declaration order. Numbered-parameter forms (`_1`, `_2`, ...) bind
+      #   `:_1`, `:_2`, ... up to the maximum the block body refers to.
       def bind(block_node)
         params_root = block_node.parameters
         return {} if params_root.nil?
@@ -81,12 +64,10 @@ module Rigor
 
       private
 
-      # `|_1, _2|` numbered-parameter form. Prism exposes the
-      # implicit count through `NumberedParametersNode#maximum`
-      # (the highest `_N` referenced in the body); we materialise
-      # bindings for `:_1` through `:_maximum` so the block body's
-      # `LocalVariableReadNode` lookups see the same types as the
-      # equivalent explicit `|x, y|` form would.
+      # `|_1, _2|` numbered-parameter form. Prism exposes the implicit count through
+      # `NumberedParametersNode#maximum` (the highest `_N` referenced in the body); we materialise bindings
+      # for `:_1` through `:_maximum` so the block body's `LocalVariableReadNode` lookups see the same types
+      # as the equivalent explicit `|x, y|` form would.
       def bind_numbered_parameters(numbered_node)
         bindings = {}
         numbered_node.maximum.times do |i|
@@ -95,9 +76,8 @@ module Rigor
         bindings
       end
 
-      # `{ it.foo }` — Ruby 3.4 `it` is a single-argument implicit
-      # parameter. Always binds the symbol `:it`; `ItLocalVariableReadNode`
-      # in the body looks the binding up by name.
+      # `{ it.foo }` — Ruby 3.4 `it` is a single-argument implicit parameter. Always binds the symbol `:it`;
+      # `ItLocalVariableReadNode` in the body looks the binding up by name.
       def bind_it_parameter
         { it: positional_type_at(0) }
       end
@@ -117,27 +97,21 @@ module Rigor
         bindings
       end
 
-      # Ruby blocks (NOT lambdas) auto-splat a single yielded
-      # Tuple-shaped value when the block declares more than one
-      # required positional parameter:
+      # Ruby blocks (NOT lambdas) auto-splat a single yielded Tuple-shaped value when the block declares more
+      # than one required positional parameter:
       #
       #   { a: 1 }.each { |k, v| ... }
       #
-      # yields `[key, value]` as a single arg, but the two-param
-      # block sees `k = key, v = value`. RBS / IteratorDispatch
-      # encode this as the block taking ONE `[K, V]` Tuple
-      # parameter; without this fix-up the binder would assign
-      # `k = Tuple[K, V]` and `v = Dynamic[Top]`, and any call
-      # on `k.<method-not-on-Tuple>` would false-fire.
+      # yields `[key, value]` as a single arg, but the two-param block sees `k = key, v = value`. RBS /
+      # IteratorDispatch encode this as the block taking ONE `[K, V]` Tuple parameter; without this fix-up
+      # the binder would assign `k = Tuple[K, V]` and `v = Dynamic[Top]`, and any call on
+      # `k.<method-not-on-Tuple>` would false-fire.
       #
-      # The rule fires only when (a) the receiver yields exactly
-      # one value (`expected_param_types.size == 1`), (b) the
-      # block declares more than one positional slot, and (c)
-      # that single expected element is a Tuple. Multi-arg yields
-      # (e.g. `each_with_index`'s `(element, index)` pair) are
-      # NOT auto-splatted — matching Ruby semantics where a
-      # multi-arg yield to a `|a, b, c|` block fills the extra
-      # slot with nil rather than splatting any element.
+      # The rule fires only when (a) the receiver yields exactly one value (`expected_param_types.size ==
+      # 1`), (b) the block declares more than one positional slot, and (c) that single expected element is a
+      # Tuple. Multi-arg yields (e.g. `each_with_index`'s `(element, index)` pair) are NOT auto-splatted —
+      # matching Ruby semantics where a multi-arg yield to a `|a, b, c|` block fills the extra slot with nil
+      # rather than splatting any element.
       def apply_auto_splat(params_node)
         return unless @expected_param_types.size == 1
 
@@ -180,11 +154,9 @@ 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. 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).
       def bind_rest(params_node, bindings)
         rest = params_node.rest
         return unless rest.respond_to?(:name) && rest&.name
@@ -219,13 +191,11 @@ module Rigor
         bindings[block.name] = Type::Combinator.nominal_of(Proc)
       end
 
-      # Required parameters in a block list can be either a plain
-      # `RequiredParameterNode` (named) or a `MultiTargetNode` (the
-      # `|(a, b), c|` destructuring form). Slice 6 phase C sub-phase 2
-      # delegates the latter to {MultiTargetBinder}, which decomposes
-      # the slot's expected Tuple element-wise and binds every named
-      # inner local. Other shapes (anonymous required parameters,
-      # forward arguments) are silently skipped.
+      # Required parameters in a block list can be either a plain `RequiredParameterNode` (named) or a
+      # `MultiTargetNode` (the `|(a, b), c|` destructuring form). Slice 6 phase C sub-phase 2 delegates the
+      # latter to {MultiTargetBinder}, which decomposes the slot's expected Tuple element-wise and binds
+      # every named inner local. Other shapes (anonymous required parameters, forward arguments) are
+      # silently skipped.
       def bind_required_param(param, cursor, bindings)
         case param
         when Prism::RequiredParameterNode

data/lib/rigor/inference/body_fixpoint.rb

@@ -5,25 +5,21 @@ require_relative "budget_trace"
 
 module Rigor
   module Inference
-    # ADR-56 WD3 — the single capped-fixpoint mechanism shared by the
-    # non-escaping block captured-local write-back (slice A) and the
-    # loop-body fixpoint (slice B). Computes the continuation binding of a
-    # set of locals that a body (a block body or a loop body) may rebind
-    # across an unknown number (0..N) of iterations.
+    # ADR-56 WD3 — the single capped-fixpoint mechanism shared by the non-escaping block captured-local
+    # write-back (slice A) and the loop-body fixpoint (slice B). Computes the continuation binding of a set of
+    # locals that a body (a block body or a loop body) may rebind across an unknown number (0..N) of
+    # iterations.
     #
-    # The body may run zero times, so the seed (pre-state) binding is kept
-    # as a join constituent throughout; it may compound (`a = [a]`), so the
-    # join is iterated to a fixed point under a hard cap (ADR-41 WD4). On
-    # the final permitted iteration value-pinned constituents are widened to
-    # their nominal base to force convergence; a local that still moves is
-    # collapsed to `Dynamic[top]` — the established escaping-block floor —
-    # and a {BudgetTrace::BLOCK_WRITEBACK_CAP} hit is recorded.
+    # The body may run zero times, so the seed (pre-state) binding is kept as a join constituent throughout; it
+    # may compound (`a = [a]`), so the join is iterated to a fixed point under a hard cap (ADR-41 WD4). On the
+    # final permitted iteration value-pinned constituents are widened to their nominal base to force
+    # convergence; a local that still moves is collapsed to `Dynamic[top]` — the established escaping-block
+    # floor — and a {BudgetTrace::BLOCK_WRITEBACK_CAP} hit is recorded.
     #
-    # The mechanism is parameterized over an `evaluate_body` callable so
-    # slice B can reuse it: given the current per-name bindings it returns
-    # the per-name exit bindings produced by one body evaluation from those
-    # bindings (names the body leaves unwritten in a given pass simply do
-    # not appear in the returned hash).
+    # The mechanism is parameterized over an `evaluate_body` callable so slice B can reuse it: given the
+    # current per-name bindings it returns the per-name exit bindings produced by one body evaluation from
+    # those bindings (names the body leaves unwritten in a given pass simply do not appear in the returned
+    # hash).
     module BodyFixpoint
       # One body evaluation per iteration; ADR-55's shape (cap 3).
       CAP = 3
@@ -33,15 +29,14 @@ module Rigor
       # @param names [Array<Symbol>] the outer locals the body can rebind.
       # @param seed_bindings [Hash{Symbol=>Type}] pre-state binding per name.
       # @param widen [#call] value-pinned widener (Constant -> Nominal).
-      # @param evaluate_body [#call] `bindings -> exit_bindings` — evaluates
-      #   the body once from `bindings` (the per-name current assumption) and
-      #   returns the per-name exit binding it produced.
+      # @param evaluate_body [#call] `bindings -> exit_bindings` — evaluates the body once from `bindings`
+      #   (the per-name current assumption) and returns the per-name exit binding it produced.
       # @return [Hash{Symbol=>Type}] the continuation binding per name.
       def converge(names:, seed_bindings:, widen:, evaluate_body:)
         return {} if names.empty?
 
-        # Running assumption per name; seeded with the pre-state binding,
-        # which stays a join constituent throughout (0-iteration soundness).
+        # Running assumption per name; seeded with the pre-state binding, which stays a join constituent
+        # throughout (0-iteration soundness).
         assumption = seed_bindings.dup
 
         (0...CAP).each do |iteration|
@@ -54,14 +49,11 @@ module Rigor
             next if exit_type.nil? # body did not write it this pass
 
             if last_iteration
-              # On the final permitted iteration widen BOTH the running
-              # assumption and the fresh exit type to their nominal bases
-              # before joining: Rigor's `union` keeps `Constant[1]` and
-              # `Nominal[Integer]` as distinct members, so an accumulator
-              # (`+=`/`*=`) producing a fresh constant per pass would never
-              # converge without collapsing both sides first. If the join
-              # is still wider than the widened assumption (structural
-              # compounding, `a = [a]`), the local floors to `Dynamic[top]`.
+              # On the final permitted iteration widen BOTH the running assumption and the fresh exit type to
+              # their nominal bases before joining: Rigor's `union` keeps `Constant[1]` and `Nominal[Integer]`
+              # as distinct members, so an accumulator (`+=`/`*=`) producing a fresh constant per pass would
+              # never converge without collapsing both sides first. If the join is still wider than the
+              # widened assumption (structural compounding, `a = [a]`), the local floors to `Dynamic[top]`.
               base = widen.call(assumption[name])
               joined = Type::Combinator.union(base, widen.call(exit_type))
               if joined == base

data/lib/rigor/inference/budget_trace.rb

@@ -2,61 +2,46 @@
 
 module Rigor
   module Inference
-    # Opt-in counters for the hard-coded inference cutoffs — the
-    # "budget" guards that silently return `Dynamic[top]` / `nil` /
-    # a fallback bound rather than emitting a diagnostic. These are
-    # the *operative* cutoffs in the engine today (the configurable
-    # `budgets:` table in docs/type-specification/inference-budgets.md
-    # is not yet wired); counting how often each fires on a real
+    # Opt-in counters for the hard-coded inference cutoffs — the "budget" guards that silently return
+    # `Dynamic[top]` / `nil` / a fallback bound rather than emitting a diagnostic. These are the *operative*
+    # cutoffs in the engine today (the configurable `budgets:` table in
+    # docs/type-specification/inference-budgets.md is not yet wired); counting how often each fires on a real
     # project is the only way to see where inference actually stops.
     #
     # Three 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).
-    # - {ANCESTOR_WALK_LIMIT} — `resolve_user_def_through_ancestors`
-    #   hit the 100-node BFS cap and gave up resolving the self-call.
-    # - {HKT_FUEL_EXHAUSTED} — `HktReducer` ran out of its reduction
-    #   fuel budget and unwound to `app.bound`.
-    # - {RECURSION_UNROLL_FUEL} — the constant-arg recursion unroll
-    #   (ADR-55 slice 1) exhausted its per-entry 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).
+    # - {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).
+    # - {ANCESTOR_WALK_LIMIT} — `resolve_user_def_through_ancestors` hit the 100-node BFS cap and gave up
+    #   resolving the self-call.
+    # - {HKT_FUEL_EXHAUSTED} — `HktReducer` ran out of its reduction fuel budget and unwound to `app.bound`.
+    # - {RECURSION_UNROLL_FUEL} — the constant-arg recursion unroll (ADR-55 slice 1) exhausted its per-entry
+    #   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).
     #
-    # 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 runs pay nothing.
+    # 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
+    # runs pay nothing.
     #
-    # Counters are process-global (Mutex-guarded) so they aggregate
-    # across threads, but they do NOT cross `fork` boundaries — run
-    # `rigor check --workers 0` to keep all inference in one process
-    # when collecting a trace.
+    # Counters are process-global (Mutex-guarded) so they aggregate across threads, but they do NOT cross
+    # `fork` boundaries — run `rigor check --workers 0` to keep all inference in one process when collecting a
+    # trace.
     module BudgetTrace
       RECURSION_GUARD = :recursion_guard
       ANCESTOR_WALK_LIMIT = :ancestor_walk_limit
       HKT_FUEL_EXHAUSTED = :hkt_fuel_exhausted
-      # `ExpressionTyper#infer_user_method_return` exhausted its
-      # constant-arg unroll fuel (ADR-55 slice 1) and fell back to the
-      # plain `(receiver, method)` recursion guard — i.e. the in-cycle
-      # call widened to `Dynamic[top]` exactly as it does without the
-      # unroll.
+      # `ExpressionTyper#infer_user_method_return` exhausted its constant-arg unroll fuel (ADR-55 slice 1) and
+      # fell back to the plain `(receiver, method)` recursion guard — i.e. the in-cycle call widened to
+      # `Dynamic[top]` exactly as it does without the unroll.
       RECURSION_UNROLL_FUEL = :recursion_unroll_fuel
-      # `ExpressionTyper#infer_user_method_return` ran the fixpoint
-      # return-summary iteration (ADR-55 slice 2) to its 3-evaluation cap
-      # without reaching convergence and collapsed the summary to
-      # `untyped` — the in-cycle result widens to `Dynamic[top]` exactly
-      # as it does without the fixpoint.
+      # `ExpressionTyper#infer_user_method_return` ran the fixpoint return-summary iteration (ADR-55 slice 2)
+      # to its 3-evaluation cap without reaching convergence and collapsed the summary to `untyped` — the
+      # in-cycle result widens to `Dynamic[top]` exactly as it does without the fixpoint.
       RECURSION_FIXPOINT_CAP = :recursion_fixpoint_cap
-      # `BodyFixpoint#converge` (ADR-56 slice A — non-escaping block
-      # captured-local write-back) ran its 3-evaluation cap without the
-      # written local's join converging and collapsed that local to
-      # `Dynamic[top]` (the escaping-block floor). Shared by slice B's
-      # loop-body fixpoint.
+      # `BodyFixpoint#converge` (ADR-56 slice A — non-escaping block captured-local write-back) ran its
+      # 3-evaluation cap without the written local's join converging and collapsed that local to
+      # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint.
       BLOCK_WRITEBACK_CAP = :block_writeback_cap
 
       CATEGORIES = [
@@ -64,12 +49,10 @@ module Rigor
         RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP
       ].freeze
 
-      # Distribution (histogram) categories — read-only observations of
-      # a value's size at a site, used to choose budget defaults from an
-      # observed tail rather than a guess (ADR-41 WD3 / Slice 2a). No cap
-      # is enforced; these only record. `UNION_ARITY` is the member count
-      # of every `Type::Union` that `Combinator.union` produces — the
-      # distribution the `union_size` budget default should be set from.
+      # Distribution (histogram) categories — read-only observations of a value's size at a site, used to
+      # choose budget defaults from an observed tail rather than a guess (ADR-41 WD3 / Slice 2a). No cap is
+      # enforced; these only record. `UNION_ARITY` is the member count of every `Type::Union` that
+      # `Combinator.union` produces — the distribution the `union_size` budget default should be set from.
       UNION_ARITY = :union_arity
 
       DISTRIBUTION_CATEGORIES = [UNION_ARITY].freeze
@@ -85,8 +68,8 @@ module Rigor
         @enabled
       end
 
-      # Test / programmatic toggles. Production enablement is the
-      # `RIGOR_BUDGET_TRACE` env var read once at load time.
+      # Test / programmatic toggles. Production enablement is the `RIGOR_BUDGET_TRACE` env var read once at
+      # load time.
       def enable!
         @enabled = true
       end
@@ -95,24 +78,23 @@ module Rigor
         @enabled = false
       end
 
-      # Records one firing of `category`. No-op (one boolean check)
-      # when tracing is disabled.
+      # Records one firing of `category`. No-op (one boolean check) when tracing is disabled.
       def hit(category)
         return unless @enabled
 
         @mutex.synchronize { @counts[category] += 1 }
       end
 
-      # Frozen snapshot of the current counts, every known category
-      # present (zero-filled) so consumers can render a stable table.
+      # Frozen snapshot of the current counts, every known category present (zero-filled) so consumers can
+      # render a stable table.
       def snapshot
         @mutex.synchronize do
           CATEGORIES.to_h { |category| [category, @counts[category]] }.freeze
         end
       end
 
-      # Records one observation of `value` (an Integer size) into
-      # `category`'s histogram. No-op (one boolean check) when disabled.
+      # Records one observation of `value` (an Integer size) into `category`'s histogram. No-op (one boolean
+      # check) when disabled.
       def observe(category, value)
         return unless @enabled
 
@@ -124,10 +106,9 @@ module Rigor
         @mutex.synchronize { @distributions[category].dup.freeze }
       end
 
-      # Summary of a distribution category: total observation count, max
-      # observed value, selected percentiles, and how many observations
-      # met or exceeded each threshold in `over`. Percentiles use the
-      # nearest-rank method over the expanded sample.
+      # Summary of a distribution category: total observation count, max observed value, selected percentiles,
+      # and how many observations met or exceeded each threshold in `over`. Percentiles use the nearest-rank
+      # method over the expanded sample.
       def summarize(category, over: [])
         hist = distribution(category)
         total = hist.values.sum
@@ -141,8 +122,7 @@ module Rigor
           over: over.to_h { |t| [t, hist.sum { |value, n| value >= t ? n : 0 }] } }
       end
 
-      # Nearest-rank percentile over a `{value => count}` histogram
-      # without materialising the full sample.
+      # Nearest-rank percentile over a `{value => count}` histogram without materialising the full sample.
       def percentile(hist, total, fraction)
         rank = (fraction * total).ceil
         cumulative = 0

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

@@ -7,12 +7,10 @@ module Rigor
     module Builtins
       # `Array` catalog. Singleton — load once, consult during dispatch.
       #
-      # Array has more mutation surface than String: every method that
-      # logically reshapes the array tends to call `rb_ary_modify` or
-      # an internal helper (`ary_replace`, `ary_resize`, `ary_pop`,
-      # `ary_push_internal`, …) that the classifier does not yet
-      # recognise. The blocklist captures the methods we have
-      # specifically observed flowing as `:leaf` despite mutating.
+      # Array has more mutation surface than String: every method that logically reshapes the array tends
+      # to call `rb_ary_modify` or an internal helper (`ary_replace`, `ary_resize`, `ary_pop`,
+      # `ary_push_internal`, …) that the classifier does not yet recognise. The blocklist captures the
+      # methods we have specifically observed flowing as `:leaf` despite mutating.
       ARRAY_CATALOG = MethodCatalog.for_topic(
         "array",
         mutating_selectors: {

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

@@ -7,12 +7,10 @@ module Rigor
     module Builtins
       # `Comparable` module catalog. Singleton — load once.
       #
-      # `Comparable` is a Ruby module, not a class, so the
-      # catalog is NOT routed through
-      # `MethodDispatcher::ConstantFolding::CATALOG_BY_CLASS`
-      # (which dispatches on the receiver's concrete class).
-      # The data is wired into `MODULE_CATALOGS` in
-      # `MethodDispatcher::ConstantFolding` (ancestor-chain lookup).
+      # `Comparable` is a Ruby module, not a class, so the catalog is NOT routed through
+      # `MethodDispatcher::ConstantFolding::CATALOG_BY_CLASS` (which dispatches on the receiver's concrete
+      # class). The data is wired into `MODULE_CATALOGS` in `MethodDispatcher::ConstantFolding`
+      # (ancestor-chain lookup).
       COMPARABLE_CATALOG = MethodCatalog.for_topic(
         "comparable",
         mutating_selectors: {

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

@@ -5,30 +5,24 @@ require_relative "method_catalog"
 module Rigor
   module Inference
     module Builtins
-      # `Complex` catalog. Singleton — load once, consult during
-      # dispatch.
+      # `Complex` catalog. Singleton — load once, consult during dispatch.
       #
-      # `Complex` is a fully-immutable value type in Ruby: once a
-      # complex number is constructed (via `Complex(real, imag)` or
-      # `Complex.rect` / `Complex.polar`) its `real` and `imag` slots
-      # are never rewritten. Every public instance method either
-      # returns `self` unchanged or builds a fresh `Complex` /
-      # `Numeric`. The C-body classifier already correctly flags the
-      # four `:dispatch` methods (`<=>`, `to_s`, `inspect`,
-      # `rationalize`) so there are no false-positive `:leaf`
-      # entries to override. The blocklist therefore carries only
-      # the conventional `:initialize_copy` defence-in-depth entry
-      # so a hypothetical future `Constant<Complex>` carrier cannot
-      # fold an aliasing copy through the catalog (mirrors
-      # `range_catalog.rb`, `time_catalog.rb`, `date_catalog.rb`).
+      # `Complex` is a fully-immutable value type in Ruby: once a complex number is constructed (via
+      # `Complex(real, imag)` or `Complex.rect` / `Complex.polar`) its `real` and `imag` slots are never
+      # rewritten. Every public instance method either returns `self` unchanged or builds a fresh
+      # `Complex` / `Numeric`. The C-body classifier already correctly flags the four `:dispatch` methods
+      # (`<=>`, `to_s`, `inspect`, `rationalize`) so there are no false-positive `:leaf` entries to
+      # override. The blocklist therefore carries only the conventional `:initialize_copy`
+      # defence-in-depth entry so a hypothetical future `Constant<Complex>` carrier cannot fold an
+      # aliasing copy through the catalog (mirrors `range_catalog.rb`, `time_catalog.rb`,
+      # `date_catalog.rb`).
       COMPLEX_CATALOG = MethodCatalog.for_topic(
         "complex",
         mutating_selectors: {
           "Complex" => Set[
-            # Defence in depth: `Complex` does not currently expose
-            # a public `initialize_copy`, but blocking it keeps the
-            # convention identical to every other catalog so future
-            # CRuby additions cannot leak a copy-mutator through.
+            # Defence in depth: `Complex` does not currently expose a public `initialize_copy`, but
+            # blocking it keeps the convention identical to every other catalog so future CRuby additions
+            # cannot leak a copy-mutator through.
             :initialize_copy
           ]
         }