rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/narrowing.rb

@@ -11,39 +11,31 @@ require_relative "../builtins/regex_refinement"
 
 module Rigor
   module Inference
-    # Control-flow predicate narrowing and type-lattice narrowing
-    # primitives.
+    # Control-flow predicate narrowing and type-lattice narrowing primitives.
     #
     # `Rigor::Inference::Narrowing` answers two related questions:
     #
-    # 1. Type-level narrowing: given a `Rigor::Type` value, what is its
-    #    truthy fragment, its falsey fragment, its nil fragment, and its
-    #    non-nil fragment? These primitives understand the value-lattice
-    #    algebra (`Constant`, `Nominal`, `Singleton`, `Tuple`, `HashShape`,
-    #    `Union`) and stay conservative on `Top` and `Dynamic[T]`.
-    # 2. Predicate-level narrowing: given a Prism predicate node and an
-    #    entry scope, what are the truthy-edge scope and the falsey-edge
-    #    scope? The catalogue covers truthiness, `nil?`, `!`, `&&`/`||`,
-    #    class-membership (`is_a?`, `kind_of?`, `instance_of?`), trusted
-    #    equality/inequality against static literals, `case`/`when`,
-    #    regex match globals, string predicates (`start_with?` etc.),
-    #    key-presence, array emptiness, numeric comparison, and
+    # 1. Type-level narrowing: given a `Rigor::Type` value, what is its truthy fragment, its
+    #    falsey fragment, its nil fragment, and its non-nil fragment? These primitives
+    #    understand the value-lattice algebra (`Constant`, `Nominal`, `Singleton`, `Tuple`,
+    #    `HashShape`, `Union`) and stay conservative on `Top` and `Dynamic[T]`.
+    # 2. Predicate-level narrowing: given a Prism predicate node and an entry scope, what are the
+    #    truthy-edge scope and the falsey-edge scope? The catalogue covers truthiness, `nil?`,
+    #    `!`, `&&`/`||`, class-membership (`is_a?`, `kind_of?`, `instance_of?`), trusted
+    #    equality/inequality against static literals, `case`/`when`, regex match globals, string
+    #    predicates (`start_with?` etc.), key-presence, array emptiness, numeric comparison, and
     #    `respond_to?`.
     #
-    # Consumed by `Rigor::Inference::StatementEvaluator` to refine
-    # `then`/`else` scopes of `IfNode`/`UnlessNode` and
-    # `case`/`when` branches.
+    # Consumed by `Rigor::Inference::StatementEvaluator` to refine `then`/`else` scopes of
+    # `IfNode`/`UnlessNode` and `case`/`when` branches.
     #
-    # The module is pure: every public function returns fresh values and
-    # MUST NOT mutate its inputs. Unrecognised predicate shapes degrade
-    # silently to "no narrowing" by returning `nil` from the internal
-    # analyser; the public `predicate_scopes` always returns an
-    # `[truthy_scope, falsey_scope]` pair (the entry scope twice when no
-    # rule matches).
+    # The module is pure: every public function returns fresh values and MUST NOT mutate its
+    # inputs. Unrecognised predicate shapes degrade silently to "no narrowing" by returning
+    # `nil` from the internal analyser; the public `predicate_scopes` always returns an
+    # `[truthy_scope, falsey_scope]` pair (the entry scope twice when no rule matches).
     #
     # See docs/internal-spec/inference-engine.md (Narrowing) and
-    # docs/type-specification/control-flow-analysis.md for the
-    # binding contract.
+    # docs/type-specification/control-flow-analysis.md for the binding contract.
     # rubocop:disable Metrics/ModuleLength
     module Narrowing
       TRUSTED_EQUALITY_LITERAL_CLASSES = [String, Symbol, Integer, TrueClass, FalseClass, NilClass].freeze
@@ -53,15 +45,13 @@ module Rigor
 
       module_function
 
-      # Truthy fragment of `type`: the subset whose inhabitants are truthy
-      # in Ruby's sense (anything other than `nil` and `false`).
+      # Truthy fragment of `type`: the subset whose inhabitants are truthy in Ruby's sense
+      # (anything other than `nil` and `false`).
       #
-      # `Top`, `Dynamic[T]`, `Bot`, `Singleton[C]`, `Tuple[*]`, and
-      # `HashShape{*}` flow through unchanged: Top/Dynamic stay
-      # conservative because the analyzer cannot express the
-      # difference type without a richer carrier and Dynamic must
-      # preserve its provenance under the value-lattice algebra; the
-      # remaining carriers are already truthy by inhabitance.
+      # `Top`, `Dynamic[T]`, `Bot`, `Singleton[C]`, `Tuple[*]`, and `HashShape{*}` flow through
+      # unchanged: Top/Dynamic stay conservative because the analyzer cannot express the
+      # difference type without a richer carrier and Dynamic must preserve its provenance under
+      # the value-lattice algebra; the remaining carriers are already truthy by inhabitance.
       def narrow_truthy(type)
         case type
         when Type::Constant
@@ -75,9 +65,8 @@ module Rigor
         end
       end
 
-      # Falsey fragment of `type`: the subset whose inhabitants are
-      # `nil` or `false`. Carriers that cannot inhabit a falsey value
-      # collapse to `Bot`.
+      # Falsey fragment of `type`: the subset whose inhabitants are `nil` or `false`. Carriers
+      # that cannot inhabit a falsey value collapse to `Bot`.
       def narrow_falsey(type)
         case type
         when Type::Constant then falsey_value?(type.value) ? type : Type::Combinator.bot
@@ -87,12 +76,10 @@ module Rigor
         end
       end
 
-      # Nil fragment of `type`: the subset whose inhabitants are `nil`.
-      # Used by `nil?` predicate narrowing. `Top`/`Dynamic` narrow to
-      # the canonical `Constant[nil]` so downstream dispatch resolves
-      # through `NilClass`; carriers that never inhabit `nil`
-      # (`Singleton`, `Tuple`, `HashShape`) collapse to `Bot`. `Bot`
-      # is its own nil fragment.
+      # Nil fragment of `type`: the subset whose inhabitants are `nil`. Used by `nil?` predicate
+      # narrowing. `Top`/`Dynamic` narrow to the canonical `Constant[nil]` so downstream
+      # dispatch resolves through `NilClass`; carriers that never inhabit `nil` (`Singleton`,
+      # `Tuple`, `HashShape`) collapse to `Bot`. `Bot` is its own nil fragment.
       def narrow_nil(type)
         case type
         when Type::Constant then type.value.nil? ? type : Type::Combinator.bot
@@ -102,9 +89,8 @@ module Rigor
         end
       end
 
-      # Non-nil fragment of `type`: the subset whose inhabitants are
-      # not `nil`. Mirror of {.narrow_nil} for the falsey edge of
-      # `x.nil?`.
+      # Non-nil fragment of `type`: the subset whose inhabitants are not `nil`. Mirror of
+      # {.narrow_nil} for the falsey edge of `x.nil?`.
       def narrow_non_nil(type)
         case type
         when Type::Constant
@@ -114,23 +100,19 @@ module Rigor
         when Type::Union
           Type::Combinator.union(*type.members.map { |m| narrow_non_nil(m) })
         else
-          # Top, Dynamic, Singleton, Tuple, HashShape, Bot: there is
-          # no nil contribution to remove, so the type is its own
-          # non-nil fragment.
+          # Top, Dynamic, Singleton, Tuple, HashShape, Bot: there is no nil contribution to
+          # remove, so the type is its own non-nil fragment.
           type
         end
       end
 
-      # Three-valued truthiness certainty of a predicate's type,
-      # derived from the truthy / falsey fragments above: `:truthy`
-      # when no inhabitant is falsey (the falsey fragment is `Bot`),
-      # `:falsey` when no inhabitant is truthy, nil when both
-      # fragments are inhabited — or when the type itself is nil /
-      # `Bot` (dead code is not a certainty claim). This is the single
-      # owner of the judgment both branch-elision consumers read
-      # (`ExpressionTyper#elide_or_union` on the value side,
-      # `StatementEvaluator#live_branch_for_if` on the scope side), so
-      # the type a dead branch is elided from and the scope that stops
+      # Three-valued truthiness certainty of a predicate's type, derived from the truthy /
+      # falsey fragments above: `:truthy` when no inhabitant is falsey (the falsey fragment is
+      # `Bot`), `:falsey` when no inhabitant is truthy, nil when both fragments are inhabited —
+      # or when the type itself is nil / `Bot` (dead code is not a certainty claim). This is the
+      # single owner of the judgment both branch-elision consumers read
+      # (`ExpressionTyper#elide_or_union` on the value side, `StatementEvaluator#live_branch_for_if`
+      # on the scope side), so the type a dead branch is elided from and the scope that stops
       # flowing through it can never disagree.
       def predicate_certainty(type)
         return nil if type.nil? || type.is_a?(Type::Bot)
@@ -144,14 +126,12 @@ module Rigor
         nil
       end
 
-      # Three-valued certainty of `C === subject` for a class / module
-      # `when` pattern, derived from {.narrow_class} /
-      # {.narrow_not_class}: `:no` when no inhabitant of the subject
-      # matches, `:yes` when every inhabitant matches, `:maybe`
-      # otherwise. The value-side counterpart of the scope narrowing
-      # {.case_when_scopes} performs for the same condition shape, kept
-      # here so the branch a `case` expression's type drops and the
-      # clause whose body scope goes dead derive from one judgment.
+      # Three-valued certainty of `C === subject` for a class / module `when` pattern, derived
+      # from {.narrow_class} / {.narrow_not_class}: `:no` when no inhabitant of the subject
+      # matches, `:yes` when every inhabitant matches, `:maybe` otherwise. The value-side
+      # counterpart of the scope narrowing {.case_when_scopes} performs for the same condition
+      # shape, kept here so the branch a `case` expression's type drops and the clause whose
+      # body scope goes dead derive from one judgment.
       def class_pattern_certainty(subject_type, class_name, environment:)
         truthy_bot = narrow_class(subject_type, class_name, environment: environment).is_a?(Type::Bot)
         falsey_bot = narrow_not_class(subject_type, class_name, environment: environment).is_a?(Type::Bot)
@@ -162,18 +142,16 @@ module Rigor
         :maybe
       end
 
-      # Classes whose `===` is plain value equality, so a literal
-      # `when` pattern against a pinned `Constant` subject is exact in
-      # both directions. Anything else keeps custom-`===` semantics
-      # and stays `:maybe` in {.value_pattern_certainty}.
+      # Classes whose `===` is plain value equality, so a literal `when` pattern against a
+      # pinned `Constant` subject is exact in both directions. Anything else keeps custom-`===`
+      # semantics and stays `:maybe` in {.value_pattern_certainty}.
       VALUE_EQUALITY_CLASSES = [Integer, Float, Rational, Complex, String, Symbol,
                                 TrueClass, FalseClass, NilClass].freeze
 
-      # Three-valued certainty of `<literal> === subject` for a
-      # value-equality literal pattern: exact (`:yes` / `:no`) only
-      # when the subject is itself a pinned `Constant` of a
-      # value-equality class; `:maybe` otherwise (the runtime value
-      # isn't pinned, or `===` may be user-defined).
+      # Three-valued certainty of `<literal> === subject` for a value-equality literal pattern:
+      # exact (`:yes` / `:no`) only when the subject is itself a pinned `Constant` of a
+      # value-equality class; `:maybe` otherwise (the runtime value isn't pinned, or `===` may
+      # be user-defined).
       def value_pattern_certainty(subject_type, pattern_value)
         return :maybe unless subject_type.is_a?(Type::Constant)
         return :maybe unless VALUE_EQUALITY_CLASSES.any? { |klass| subject_type.value.is_a?(klass) }
@@ -183,10 +161,9 @@ module Rigor
 
       # Equality fragment of `type` against a trusted literal.
       #
-      # String/Symbol/Integer equality narrows only when the current
-      # domain is already a finite union of trusted literals. Nil and
-      # booleans are singleton values, so they can be extracted from a
-      # mixed union such as `Integer | nil` without manufacturing a new
+      # String/Symbol/Integer equality narrows only when the current domain is already a
+      # finite union of trusted literals. Nil and booleans are singleton values, so they can be
+      # extracted from a mixed union such as `Integer | nil` without manufacturing a new
       # positive domain from the comparison alone.
       def narrow_equal(type, literal)
         return type unless trusted_equality_literal?(literal)
@@ -200,9 +177,9 @@ module Rigor
         end
       end
 
-      # Complement of {.narrow_equal}. Negative facts are domain-relative:
-      # they remove a literal from an already-known domain but do not create
-      # an unbounded difference type when the domain is broad or dynamic.
+      # Complement of {.narrow_equal}. Negative facts are domain-relative: they remove a literal
+      # from an already-known domain but do not create an unbounded difference type when the
+      # domain is broad or dynamic.
       def narrow_not_equal(type, literal)
         return type unless trusted_equality_literal?(literal)
 
@@ -215,46 +192,41 @@ module Rigor
         end
       end
 
-      # Integer-comparison fragment of `type` against an Integer
-      # literal `bound`. Narrows the receiver of `x < n`, `x <= n`,
-      # `x > n`, `x >= n` (and the reversed forms) to the subset of
-      # the existing domain that satisfies the comparison. Hooks in:
-      # - `Constant<Integer>` is preserved when it satisfies the
-      #   comparison, otherwise collapsed to `Bot`.
-      # - `IntegerRange[a..b]` becomes the intersection with the
-      #   half-line implied by the comparison; an empty intersection
-      #   collapses to `Bot`, a single-point intersection collapses
-      #   to `Constant<Integer>`.
-      # - `Nominal[Integer]` becomes the half-line itself (e.g.
-      #   `x > 0` on `Nominal[Integer]` is `positive_int`).
+      # Integer-comparison fragment of `type` against an Integer literal `bound`. Narrows the
+      # receiver of `x < n`, `x <= n`, `x > n`, `x >= n` (and the reversed forms) to the subset
+      # of the existing domain that satisfies the comparison. Hooks in:
+      # - `Constant<Integer>` is preserved when it satisfies the comparison, otherwise collapsed
+      #   to `Bot`.
+      # - `IntegerRange[a..b]` becomes the intersection with the half-line implied by the
+      #   comparison; an empty intersection collapses to `Bot`, a single-point intersection
+      #   collapses to `Constant<Integer>`.
+      # - `Nominal[Integer]` becomes the half-line itself (e.g. `x > 0` on `Nominal[Integer]` is
+      #   `positive_int`).
       # - `Union` narrows each member independently.
-      # - Other carriers (Float, String, Top, Dynamic) flow through
-      #   unchanged: the analyzer does not have a Float-range carrier
-      #   today, and no other carrier participates in numeric ordering.
+      # - Other carriers (Float, String, Top, Dynamic) flow through unchanged: the analyzer does
+      #   not have a Float-range carrier today, and no other carrier participates in numeric
+      #   ordering.
       def narrow_integer_comparison(type, comparator, bound)
         return type unless bound.is_a?(Integer) && %i[< <= > >=].include?(comparator)
 
         narrow_integer_comparison_dispatch(type, comparator, bound)
       end
 
-      # Equality fragment of `type` against an Integer `value`.
-      # `Constant<Integer>` is preserved when it equals `value`,
-      # otherwise collapses to `Bot`. `IntegerRange` covers? `value`
-      # narrows to `Constant[value]`; an out-of-range comparison
-      # collapses to `Bot`. `Nominal[Integer]` narrows to
-      # `Constant[value]`. `Union` narrows each member.
+      # Equality fragment of `type` against an Integer `value`. `Constant<Integer>` is preserved
+      # when it equals `value`, otherwise collapses to `Bot`. `IntegerRange` covers? `value`
+      # narrows to `Constant[value]`; an out-of-range comparison collapses to `Bot`.
+      # `Nominal[Integer]` narrows to `Constant[value]`. `Union` narrows each member.
       def narrow_integer_equal(type, value)
         return type unless value.is_a?(Integer)
 
         narrow_integer_equal_dispatch(type, value)
       end
 
-      # Complement of {.narrow_integer_equal}. Removes a single
-      # integer value from the domain when one endpoint of an
-      # `IntegerRange` is exactly that value (so the result stays a
-      # contiguous range). Domains where the value sits strictly
-      # between the endpoints stay unchanged: punching a hole would
-      # require a two-piece carrier the lattice does not yet model.
+      # Complement of {.narrow_integer_equal}. Removes a single integer value from the domain
+      # when one endpoint of an `IntegerRange` is exactly that value (so the result stays a
+      # contiguous range). Domains where the value sits strictly between the endpoints stay
+      # unchanged: punching a hole would require a two-piece carrier the lattice does not yet
+      # model.
       def narrow_integer_not_equal(type, value)
         return type unless value.is_a?(Integer)
 
@@ -270,70 +242,54 @@ module Rigor
         end
       end
 
-      # Class-membership fragment of `type`: the subset whose
-      # inhabitants are instances of `class_name` (or its subclasses
-      # when `exact: false`). `class_name` is the qualified name of
-      # the class as it appears in source (`"Integer"`, `"Foo::Bar"`).
-      # Slice 6 phase 2 sub-phase 1 narrows the `if x.is_a?(C)`
-      # / `if x.kind_of?(C)` / `if x.instance_of?(C)` truthy edge.
+      # Class-membership fragment of `type`: the subset whose inhabitants are instances of
+      # `class_name` (or its subclasses when `exact: false`). `class_name` is the qualified name
+      # of the class as it appears in source (`"Integer"`, `"Foo::Bar"`). Slice 6 phase 2
+      # sub-phase 1 narrows the `if x.is_a?(C)` / `if x.kind_of?(C)` / `if x.instance_of?(C)`
+      # truthy edge.
       #
-      # Nominal narrowing is hierarchy-aware through the analyzer
-      # environment: when the bound type is a supertype of
-      # `class_name` the result narrows DOWN to `Nominal[class_name]`
-      # (e.g., `Numeric & Integer = Integer`); when the bound type is
-      # already a subtype it is preserved; disjoint hierarchies
-      # collapse to `Bot`. Classes the environment cannot resolve
-      # fall back to the conservative answer (the type unchanged) so
-      # the analyzer never asserts narrowing it cannot prove.
+      # Nominal narrowing is hierarchy-aware through the analyzer environment: when the bound
+      # type is a supertype of `class_name` the result narrows DOWN to `Nominal[class_name]`
+      # (e.g., `Numeric & Integer = Integer`); when the bound type is already a subtype it is
+      # preserved; disjoint hierarchies collapse to `Bot`. Classes the environment cannot
+      # resolve fall back to the conservative answer (the type unchanged) so the analyzer never
+      # asserts narrowing it cannot prove.
       def narrow_class(type, class_name, exact: false, environment: Environment.default)
         context = ClassNarrowingContext.new(exact: exact, polarity: :positive, environment: environment)
         narrow_class_dispatch(type, class_name, context)
       end
 
-      # Mirror of {.narrow_class} for the falsey edge of
-      # `is_a?`/`kind_of?`/`instance_of?`. Inhabitants that DO
-      # satisfy the predicate are removed; inhabitants that do not
-      # are preserved. Conservative on Top/Dynamic/Bot (preserved
-      # unchanged) because the analyzer cannot prove the negative
-      # without a richer carrier.
+      # Mirror of {.narrow_class} for the falsey edge of `is_a?`/`kind_of?`/`instance_of?`.
+      # Inhabitants that DO satisfy the predicate are removed; inhabitants that do not are
+      # preserved. Conservative on Top/Dynamic/Bot (preserved unchanged) because the analyzer
+      # cannot prove the negative without a richer carrier.
       def narrow_not_class(type, class_name, exact: false, environment: Environment.default)
         context = ClassNarrowingContext.new(exact: exact, polarity: :negative, environment: environment)
         narrow_class_dispatch(type, class_name, context)
       end
 
-      # Negation pair for `assert_value is ~refinement` /
-      # `predicate-if-* … is ~refinement` directives. Computes
-      # the complement of `refinement` within the current
-      # local's domain `current_type`.
+      # Negation pair for `assert_value is ~refinement` / `predicate-if-* … is ~refinement`
+      # directives. Computes the complement of `refinement` within the current local's domain
+      # `current_type`.
       #
       # Carrier-by-carrier rules:
       #
-      # - `Difference[base, Constant[v]]`. Complement of
-      #   `base \ {v}` within `current_type`. Walk the current
-      #   type's union members, keep each part disjoint from
-      #   `base`, and add the removed-value Constant once when
-      #   any current member covers it. `assert s is
-      #   ~non-empty-string` over `s: String | nil` narrows to
-      #   `Constant[""] | NilClass`.
-      # - `IntegerRange[a, b]` (v0.0.5+ slice). Complement is
-      #   the two open halves `int<min, a-1>` and
-      #   `int<b+1, max>`, each intersected with the
-      #   integer-domain parts of `current_type`. Non-integer
-      #   parts (nil, String, …) of a Union receiver survive
-      #   unchanged. `assert n is ~int<5, 10>` over `n:
-      #   Integer | nil` narrows to `int<min, 4> | int<11,
-      #   max> | NilClass`.
-      # - `Type::Intersection[M1, M2, …]` (v0.0.5+ slice). De
-      #   Morgan: `D \ (M1 ∩ M2) = (D \ M1) ∪ (D \ M2)`. Each
-      #   member's complement is computed independently within
-      #   `current_type` and the results are unioned. Members
-      #   the algebra cannot complement (Refined, non-Constant
-      #   Difference, …) contribute `current_type` itself, so
-      #   the union widens the answer to `current_type` —
-      #   sound but imprecise.
-      # - `Refined[base, predicate]`. Predicate complements are
-      #   not reducible to a finite carrier without a richer
-      #   shape (e.g. `~lowercase-string` is "uppercase OR
+      # - `Difference[base, Constant[v]]`. Complement of `base \ {v}` within `current_type`.
+      #   Walk the current type's union members, keep each part disjoint from `base`, and add
+      #   the removed-value Constant once when any current member covers it. `assert s is
+      #   ~non-empty-string` over `s: String | nil` narrows to `Constant[""] | NilClass`.
+      # - `IntegerRange[a, b]` (v0.0.5+ slice). Complement is the two open halves `int<min,
+      #   a-1>` and `int<b+1, max>`, each intersected with the integer-domain parts of
+      #   `current_type`. Non-integer parts (nil, String, …) of a Union receiver survive
+      #   unchanged. `assert n is ~int<5, 10>` over `n: Integer | nil` narrows to `int<min, 4> |
+      #   int<11, max> | NilClass`.
+      # - `Type::Intersection[M1, M2, …]` (v0.0.5+ slice). De Morgan: `D \ (M1 ∩ M2) = (D \ M1)
+      #   ∪ (D \ M2)`. Each member's complement is computed independently within
+      #   `current_type` and the results are unioned. Members the algebra cannot complement
+      #   (Refined, non-Constant Difference, …) contribute `current_type` itself, so the union
+      #   widens the answer to `current_type` — sound but imprecise.
+      # - `Refined[base, predicate]`. Predicate complements are not reducible to a finite
+      #   carrier without a richer shape (e.g. `~lowercase-string` is "uppercase OR
       #   mixed-case"); `current_type` is returned unchanged.
       def narrow_not_refinement(current_type, refinement_type)
         case refinement_type
@@ -352,15 +308,12 @@ module Rigor
         end
       end
 
-      # ADR-7 § "Slice 4-A" — public Fact-shaped narrowing
-      # entry. Distinguishes a `Nominal[<class>]`-typed Fact
-      # (uses `narrow_class` / `narrow_not_class` for
-      # hierarchy-aware narrowing) from a refinement-shaped
-      # Fact (refined types, IntegerRange, Difference, …).
-      # The implementation lives next to its sibling helpers
-      # `narrow_class` and `narrow_not_refinement`; consumers
-      # outside `Narrowing` (today: `StatementEvaluator`'s
-      # post-return assertion path) reach for it via
+      # ADR-7 § "Slice 4-A" — public Fact-shaped narrowing entry. Distinguishes a
+      # `Nominal[<class>]`-typed Fact (uses `narrow_class` / `narrow_not_class` for
+      # hierarchy-aware narrowing) from a refinement-shaped Fact (refined types, IntegerRange,
+      # Difference, …). The implementation lives next to its sibling helpers `narrow_class` and
+      # `narrow_not_refinement`; consumers outside `Narrowing` (today:
+      # `StatementEvaluator`'s post-return assertion path) reach for it via
       # `Rigor::Inference::Narrowing.narrow_for_fact`.
       def narrow_for_fact(current, fact, environment)
         if fact.type.is_a?(Type::Nominal) && fact.type.type_args.empty?
@@ -375,9 +328,8 @@ module Rigor
         fact.type
       end
 
-      # Public predicate analyser. Returns `[truthy_scope, falsey_scope]`,
-      # always; when no narrowing rule matches the predicate node both
-      # entries are the receiver scope unchanged.
+      # Public predicate analyser. Returns `[truthy_scope, falsey_scope]`, always; when no
+      # narrowing rule matches the predicate node both entries are the receiver scope unchanged.
       #
       # @param node [Prism::Node, nil]
       # @param scope [Rigor::Scope]
@@ -391,29 +343,21 @@ module Rigor
 
       # Slice 7 phase 5 — `case`/`when` narrowing.
       #
-      # Given the subject of a `case` (the expression after the
-      # `case` keyword) and an array of `when`-clause condition
-      # nodes (`when_clause.conditions`), returns a pair of
-      # scopes:
+      # Given the subject of a `case` (the expression after the `case` keyword) and an array of
+      # `when`-clause condition nodes (`when_clause.conditions`), returns a pair of scopes:
       #
-      # - `body_scope`: the scope under which the body of the
-      #   `when` clause MUST be evaluated. The subject local is
-      #   narrowed by the union of every condition's truthy
-      #   edge so the body sees the most specific type
-      #   compatible with "any of the conditions matched".
-      # - `falsey_scope`: the scope under which the next branch
-      #   (the next `when` or the `else`) MUST be evaluated.
-      #   The subject is narrowed by the conjunction of every
-      #   condition's falsey edge.
+      # - `body_scope`: the scope under which the body of the `when` clause MUST be evaluated.
+      #   The subject local is narrowed by the union of every condition's truthy edge so the
+      #   body sees the most specific type compatible with "any of the conditions matched".
+      # - `falsey_scope`: the scope under which the next branch (the next `when` or the `else`)
+      #   MUST be evaluated. The subject is narrowed by the conjunction of every condition's
+      #   falsey edge.
       #
-      # The narrowing is best-effort: if the subject is not a
-      # `Prism::LocalVariableReadNode` or none of the condition
-      # shapes are recognised, both returned scopes equal the
-      # input scope. The catalogue mirrors
-      # {.case_equality_target_class}: static class/module
-      # constants narrow as `is_a?`; integer/float-endpoint
-      # ranges narrow to `Numeric`; string-endpoint ranges and
-      # regexp literals narrow to `String`.
+      # The narrowing is best-effort: if the subject is not a `Prism::LocalVariableReadNode` or
+      # none of the condition shapes are recognised, both returned scopes equal the input
+      # scope. The catalogue mirrors {.case_equality_target_class}: static class/module
+      # constants narrow as `is_a?`; integer/float-endpoint ranges narrow to `Numeric`;
+      # string-endpoint ranges and regexp literals narrow to `String`.
       #
       # @param subject [Prism::Node, nil] the `case` subject.
       # @param conditions [Array<Prism::Node>] the `when`
@@ -421,12 +365,10 @@ module Rigor
       # @param scope [Rigor::Scope]
       # @return [Array(Rigor::Scope, Rigor::Scope)]
       def case_when_scopes(subject, conditions, scope)
-        # C1 — `case x when /re/` runs `/re/ === x`, which sets the
-        # regex match-data globals exactly as a successful `=~` does.
-        # Narrow `$~`/`$&`/`$1..$N` on the clause body (the match
-        # edge); the falsey scope keeps the entry globals because a
-        # later clause may match a different regex. Applied even when
-        # the subject is not a narrowable local read.
+        # C1 — `case x when /re/` runs `/re/ === x`, which sets the regex match-data globals
+        # exactly as a successful `=~` does. Narrow `$~`/`$&`/`$1..$N` on the clause body (the
+        # match edge); the falsey scope keeps the entry globals because a later clause may match
+        # a different regex. Applied even when the subject is not a narrowable local read.
         body_scope = apply_when_regex_globals(conditions, scope)
 
         return [body_scope, scope] unless subject.is_a?(Prism::LocalVariableReadNode)
@@ -440,14 +382,12 @@ module Rigor
         [truthy, falsey]
       end
 
-      # When the clause has exactly one `RegularExpressionNode`
-      # literal condition, narrow the match-data globals on the body
-      # edge (same rule as `analyse_regex_match_predicate`'s truthy
-      # edge). With multiple regex conditions (`when /a/, /b/`) the
-      # body is reachable through any of them, so only `$~`/`$&` are
-      # safely non-nil; numbered groups whose presence differs per
-      # alternative stay `String | nil`. With no regex condition the
-      # entry scope passes through unchanged.
+      # When the clause has exactly one `RegularExpressionNode` literal condition, narrow the
+      # match-data globals on the body edge (same rule as `analyse_regex_match_predicate`'s
+      # truthy edge). With multiple regex conditions (`when /a/, /b/`) the body is reachable
+      # through any of them, so only `$~`/`$&` are safely non-nil; numbered groups whose
+      # presence differs per alternative stay `String | nil`. With no regex condition the entry
+      # scope passes through unchanged.
       def apply_when_regex_globals(conditions, scope)
         regexes = conditions.grep(Prism::RegularExpressionNode)
         return scope if regexes.empty?
@@ -462,10 +402,9 @@ module Rigor
         truthy
       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.
+      # 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.
       def analyse(node, scope)
         case node
         when Prism::ParenthesesNode
@@ -497,15 +436,12 @@ module Rigor
       class << self
         private
 
-        # Complement of `Difference[base, Constant[v]]` within
-        # `current_type`. Walks the current type's union members,
-        # keeps each member disjoint from `base` (those values
-        # were never in the refinement to begin with), and adds
-        # the removed-value `Constant[v]` exactly once when any
-        # current member covers it. Members that are fully
-        # contained in the refinement (i.e. inside `base` and
-        # NOT equal to the removed value) are dropped — they are
-        # exactly the values the negation excludes.
+        # Complement of `Difference[base, Constant[v]]` within `current_type`. Walks the
+        # current type's union members, keeps each member disjoint from `base` (those values
+        # were never in the refinement to begin with), and adds the removed-value `Constant[v]`
+        # exactly once when any current member covers it. Members that are fully contained in
+        # the refinement (i.e. inside `base` and NOT equal to the removed value) are dropped —
+        # they are exactly the values the negation excludes.
         def complement_difference(current_type, difference)
           base = difference.base
           removed = difference.removed
@@ -536,13 +472,11 @@ module Rigor
           result.yes? || result.maybe?
         end
 
-        # Complement of an `IntegerRange[a, b]` within
-        # `current_type`. Splits the range complement into the
-        # two open halves `int<min, a-1>` and `int<b+1, max>`
-        # (skipping a half when its bound is infinity), then
-        # intersects each half with the integer-domain parts of
-        # `current_type`. Non-integer parts of a Union receiver
-        # (nil, String, …) survive unchanged.
+        # Complement of an `IntegerRange[a, b]` within `current_type`. Splits the range
+        # complement into the two open halves `int<min, a-1>` and `int<b+1, max>` (skipping a
+        # half when its bound is infinity), then intersects each half with the integer-domain
+        # parts of `current_type`. Non-integer parts of a Union receiver (nil, String, …)
+        # survive unchanged.
         def complement_integer_range(current_type, range)
           halves = integer_range_complement_halves(range)
           parts = current_type.is_a?(Type::Union) ? current_type.members : [current_type]
@@ -564,11 +498,10 @@ module Rigor
           Type::Combinator.union(*survivors)
         end
 
-        # Returns the two open halves of an IntegerRange's
-        # complement: the left half `int<-∞, a-1>` (when `a` is
-        # finite) and the right half `int<b+1, ∞>` (when `b` is
-        # finite). Universal ranges (both bounds infinite) yield
-        # an empty array — the complement is empty.
+        # Returns the two open halves of an IntegerRange's complement: the left half `int<-∞,
+        # a-1>` (when `a` is finite) and the right half `int<b+1, ∞>` (when `b` is finite).
+        # Universal ranges (both bounds infinite) yield an empty array — the complement is
+        # empty.
         def integer_range_complement_halves(range)
           halves = []
           left_max = range.min
@@ -592,12 +525,10 @@ module Rigor
           end
         end
 
-        # Intersect an integer-domain part with a complement
-        # half-range. For a Nominal[Integer] receiver the meet
-        # is the half itself; for an existing IntegerRange the
-        # meet narrows both bounds; for a Constant[Integer] the
-        # meet is the constant when the half covers it,
-        # otherwise nil.
+        # Intersect an integer-domain part with a complement half-range. For a
+        # Nominal[Integer] receiver the meet is the half itself; for an existing IntegerRange
+        # the meet narrows both bounds; for a Constant[Integer] the meet is the constant when
+        # the half covers it, otherwise nil.
         def intersect_integer_part(part, half)
           case part
           when Type::Nominal
@@ -638,11 +569,9 @@ module Rigor
           low > high
         end
 
-        # De Morgan: `D \ (M1 ∩ M2 ∩ …) = (D \ M1) ∪ (D \ M2) ∪
-        # …`. Each member's complement is computed independently
-        # within `current_type` and the results are unioned.
-        # Members the algebra cannot complement contribute
-        # `current_type` itself, so the union widens to
+        # De Morgan: `D \ (M1 ∩ M2 ∩ …) = (D \ M1) ∪ (D \ M2) ∪ …`. Each member's complement is
+        # computed independently within `current_type` and the results are unioned. Members the
+        # algebra cannot complement contribute `current_type` itself, so the union widens to
         # `current_type` overall — sound but imprecise.
         def complement_intersection(current_type, intersection)
           per_member = intersection.members.map do |member|
@@ -651,29 +580,22 @@ module Rigor
           Type::Combinator.union(*per_member)
         end
 
-        # v0.0.7 — complement of a `Refined[base, predicate]`
-        # refinement within `current_type`. Walks the current
-        # type's union members; parts that are disjoint from
-        # the refinement's base survive unchanged; parts equal
-        # to the refinement itself drop entirely (they were
-        # exactly the negated subset); parts that overlap the
-        # base contribute `Difference[part, refined]` so
-        # downstream narrowing knows the refinement subset is
-        # excluded.
+        # v0.0.7 — complement of a `Refined[base, predicate]` refinement within `current_type`.
+        # Walks the current type's union members; parts that are disjoint from the refinement's
+        # base survive unchanged; parts equal to the refinement itself drop entirely (they were
+        # exactly the negated subset); parts that overlap the base contribute `Difference[part,
+        # refined]` so downstream narrowing knows the refinement subset is excluded.
         #
-        # v0.0.9 — when the predicate has a registered
-        # complement (see {Type::Refined::COMPLEMENT_PAIRS}) and
-        # the part is exactly the refinement's base, the
-        # narrowing returns `Refined[base, complement_predicate]`
-        # instead of `Difference[base, refined]`. This is the
-        # `~T` symmetry the spec promises: `~lowercase-string`
-        # narrows `String` to `non-lowercase-string` rather than
+        # v0.0.9 — when the predicate has a registered complement (see
+        # {Type::Refined::COMPLEMENT_PAIRS}) and the part is exactly the refinement's base, the
+        # narrowing returns `Refined[base, complement_predicate]` instead of
+        # `Difference[base, refined]`. This is the `~T` symmetry the spec promises:
+        # `~lowercase-string` narrows `String` to `non-lowercase-string` rather than
         # `Difference[String, lowercase-string]`.
         #
-        # Predicates without a registered complement still fall
-        # back to the imprecise but sound `Difference[part,
-        # refined]` carrier so behaviour is unchanged for
-        # untouched call sites.
+        # Predicates without a registered complement still fall back to the imprecise but sound
+        # `Difference[part, refined]` carrier so behaviour is unchanged for untouched call
+        # sites.
         def complement_refined(current_type, refined)
           complement = registered_complement_for(refined)
           parts = current_type.is_a?(Type::Union) ? current_type.members : [current_type]
@@ -706,10 +628,9 @@ module Rigor
           %w[NilClass FalseClass].include?(nominal.class_name)
         end
 
-        # Carriers that the {.narrow_falsey} fast path does not handle
-        # by structural inspection. Singleton/Tuple/HashShape inhabit
-        # truthy values, so their falsey fragment is empty; everything
-        # else (Top, Dynamic, Bot, and any future carrier) stays
+        # Carriers that the {.narrow_falsey} fast path does not handle by structural
+        # inspection. Singleton/Tuple/HashShape inhabit truthy values, so their falsey fragment
+        # is empty; everything else (Top, Dynamic, Bot, and any future carrier) stays
         # conservative and is returned unchanged.
         def narrow_falsey_other(type)
           case type
@@ -718,12 +639,10 @@ module Rigor
           end
         end
 
-        # Carriers that the {.narrow_nil} fast path does not handle by
-        # structural inspection. Top/Dynamic narrow to `Constant[nil]`
-        # so dispatch resolves through `NilClass`; Bot is its own nil
-        # fragment; the remaining carriers (Singleton, Tuple,
-        # HashShape, and any future carrier whose inhabitants exclude
-        # nil) collapse to `Bot`.
+        # Carriers that the {.narrow_nil} fast path does not handle by structural inspection.
+        # Top/Dynamic narrow to `Constant[nil]` so dispatch resolves through `NilClass`; Bot is
+        # its own nil fragment; the remaining carriers (Singleton, Tuple, HashShape, and any
+        # future carrier whose inhabitants exclude nil) collapse to `Bot`.
         def narrow_nil_other(type)
           case type
           when Type::Dynamic, Type::Top then Type::Combinator.constant_of(nil)
@@ -811,13 +730,11 @@ module Rigor
           analyse(node.body, scope)
         end
 
-        # The truthiness of a `StatementsNode` is determined by its
-        # last statement (intermediate statements run for effect and
-        # then the predicate's value is the tail's). Earlier
-        # statements MAY have scope effects, but Slice 6 phase 1 does
-        # NOT thread those through the analyser (the StatementEvaluator
-        # has already produced `post_pred` for the call site, and
-        # narrowing is layered on that scope).
+        # The truthiness of a `StatementsNode` is determined by its last statement
+        # (intermediate statements run for effect and then the predicate's value is the
+        # tail's). Earlier statements MAY have scope effects, but Slice 6 phase 1 does NOT
+        # thread those through the analyser (the StatementEvaluator has already produced
+        # `post_pred` for the call site, and narrowing is layered on that scope).
         def analyse_statements(node, scope)
           return nil if node.body.empty?
 
@@ -834,19 +751,15 @@ module Rigor
           ]
         end
 
-        # Assignment-in-condition: `if name = expr` and the more
-        # frequent `if cond && (name = expr)` / `if cond && name =
-        # expr` Redmine-style guard. By the time narrowing runs,
-        # `StatementEvaluator#eval_local_write` has already bound
-        # the assigned local in `scope` to the rvalue type. The
-        # write's own truthiness IS the assigned value's
-        # truthiness, so the truthy edge narrows the local by
-        # `narrow_truthy(current)` and the falsey edge by
-        # `narrow_falsey(current)`. Mirrors `analyse_local_read`
-        # because the only meaningful difference between
-        # "predicate is `var`" and "predicate is `var = expr`" is
-        # which scope holds the just-bound value; the narrowing
-        # contract on the surrounding `if` is the same.
+        # Assignment-in-condition: `if name = expr` and the more frequent `if cond && (name =
+        # expr)` / `if cond && name = expr` Redmine-style guard. By the time narrowing runs,
+        # `StatementEvaluator#eval_local_write` has already bound the assigned local in `scope`
+        # to the rvalue type. The write's own truthiness IS the assigned value's truthiness, so
+        # the truthy edge narrows the local by `narrow_truthy(current)` and the falsey edge by
+        # `narrow_falsey(current)`. Mirrors `analyse_local_read` because the only meaningful
+        # difference between "predicate is `var`" and "predicate is `var = expr`" is which scope
+        # 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?
@@ -857,16 +770,13 @@ module Rigor
           ]
         end
 
-        # Truthy guard on an instance variable. Covers both the bare
-        # read — `if @ivar`, the left arm of `@ivar && @ivar.foo`,
-        # the receiver of `unless @ivar.nil?` once `!` reverses it —
-        # and the assignment-in-condition write `if @ivar = expr`.
-        # Mirrors `analyse_local_read` / `analyse_local_write`: the
-        # truthy edge narrows the ivar by `narrow_truthy` (dropping
-        # `nil` / `false`), the falsey edge by `narrow_falsey`. The
-        # narrowing is scoped to the guarded branch only, so it is
-        # purely additive — it never widens or re-narrows the ivar
-        # binding seen elsewhere.
+        # Truthy guard on an instance variable. Covers both the bare read — `if @ivar`, the
+        # left arm of `@ivar && @ivar.foo`, the receiver of `unless @ivar.nil?` once `!`
+        # reverses it — and the assignment-in-condition write `if @ivar = expr`. Mirrors
+        # `analyse_local_read` / `analyse_local_write`: the truthy edge narrows the ivar by
+        # `narrow_truthy` (dropping `nil` / `false`), the falsey edge by `narrow_falsey`. The
+        # narrowing is scoped to the guarded branch only, so it is purely additive — it never
+        # widens or re-narrows the ivar binding seen elsewhere.
         def analyse_ivar(node, scope)
           current = scope.ivar(node.name)
           return nil if current.nil?
@@ -897,24 +807,18 @@ module Rigor
           ]
         end
 
-        # `if /(?<x>...)/ =~ str` — Prism wraps the `=~` call in a
-        # `MatchWriteNode` listing the named-capture targets. The
-        # parent `eval_match_write` has already bound each target
-        # to `String | nil`; in the truthy branch (the regex
-        # matched) every named capture is guaranteed `String`,
-        # and in the falsey branch (no match) every capture is
-        # `nil`. Subtract the dead half on each edge so callers
-        # like `year.upcase` inside the truthy branch no longer
-        # fire `possible-nil-receiver`.
+        # `if /(?<x>...)/ =~ str` — Prism wraps the `=~` call in a `MatchWriteNode` listing the
+        # named-capture targets. The parent `eval_match_write` has already bound each target to
+        # `String | nil`; in the truthy branch (the regex matched) every named capture is
+        # guaranteed `String`, and in the falsey branch (no match) every capture is `nil`.
+        # Subtract the dead half on each edge so callers like `year.upcase` inside the truthy
+        # branch no longer fire `possible-nil-receiver`.
         #
-        # v0.1.1 Track 1 slice 1 — when the regex source is a
-        # statically known `RegularExpressionNode` and a named
-        # capture's body matches one of the curated shapes in
-        # {Rigor::Builtins::RegexRefinement::RULES}, the truthy
-        # branch narrows further than `String` to the matching
-        # imported refinement (e.g. `decimal-int-string` for
-        # `\d+`). Bodies outside the table fall back to the
-        # v0.1.0 baseline (plain `String`).
+        # v0.1.1 Track 1 slice 1 — when the regex source is a statically known
+        # `RegularExpressionNode` and a named capture's body matches one of the curated shapes
+        # in {Rigor::Builtins::RegexRefinement::RULES}, the truthy branch narrows further than
+        # `String` to the matching imported refinement (e.g. `decimal-int-string` for `\d+`).
+        # Bodies outside the table fall back to the v0.1.0 baseline (plain `String`).
         def analyse_match_write(node, scope)
           string_t = Type::Combinator.nominal_of("String")
           nil_t = Type::Combinator.constant_of(nil)
@@ -930,12 +834,10 @@ module Rigor
           [truthy, falsey]
         end
 
-        # Extracts `{ capture_name => Refinement }` for every named
-        # capture group in the `MatchWriteNode`'s wrapped `=~` call
-        # whose body the recogniser table accepts. Bodies that
-        # contain nested groups, anchors, alternation, or anything
-        # else outside the curated forms drop out and the caller
-        # falls back to plain `String`.
+        # Extracts `{ capture_name => Refinement }` for every named capture group in the
+        # `MatchWriteNode`'s wrapped `=~` call whose body the recogniser table accepts. Bodies
+        # that contain nested groups, anchors, alternation, or anything else outside the curated
+        # forms drop out and the caller falls back to plain `String`.
         NAMED_CAPTURE_BODY_RE = /\(\?<([A-Za-z_][A-Za-z0-9_]*)>([^()|]*)\)/
         private_constant :NAMED_CAPTURE_BODY_RE
 
@@ -954,13 +856,12 @@ module Rigor
         # 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.
+        # - `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.
         def analyse_call(node, scope)
           return nil if node.block
 
@@ -972,42 +873,32 @@ module Rigor
             string_predicate_result = analyse_string_predicate(node, scope)
             return apply_safe_nav_non_nil(node, scope, string_predicate_result) if string_predicate_result
 
-            # A safe-navigation call (`v&.foo`) whose result is truthy
-            # proves the receiver was non-nil — `&.` returns `nil` when
-            # the receiver is nil, so a truthy outcome can only come from
-            # a non-nil receiver. Narrow the receiver on the truthy edge
-            # even when the call itself carries no other flow fact, so
-            # `v&.start_with?('[') && v.end_with?(']')` sees `v` non-nil
-            # in the `&&` right operand. The falsey edge is the
-            # conservative no-op (falsey could mean nil receiver OR a
-            # falsey method result).
+            # A safe-navigation call (`v&.foo`) whose result is truthy proves the receiver was
+            # non-nil — `&.` returns `nil` when the receiver is nil, so a truthy outcome can
+            # only come from a non-nil receiver. Narrow the receiver on the truthy edge even
+            # when the call itself carries no other flow fact, so `v&.start_with?('[') &&
+            # v.end_with?(']')` sees `v` non-nil in the `&&` right operand. The falsey edge is
+            # the conservative no-op (falsey could mean nil receiver OR a falsey method result).
             safe_nav_result = analyse_safe_nav_receiver(node, scope)
             return safe_nav_result if safe_nav_result
           end
 
-          # Slice 7 phase 15 — RBS::Extended predicate
-          # effects. When the method's RBS signature carries
-          # `rigor:v1:predicate-if-true` / `predicate-if-false`
-          # annotations, apply them to narrow the corresponding
-          # local-variable arguments on each edge. v0.1.1 Track
-          # 1 slice 3 — implicit-self calls (`recv == nil`,
-          # e.g. `admin?` inside an instance method body) flow
-          # through here too so `self`-targeted facts can edit
+          # Slice 7 phase 15 — RBS::Extended predicate effects. When the method's RBS signature
+          # carries `rigor:v1:predicate-if-true` / `predicate-if-false` annotations, apply them
+          # to narrow the corresponding local-variable arguments on each edge. v0.1.1 Track 1
+          # slice 3 — implicit-self calls (`recv == nil`, e.g. `admin?` inside an instance
+          # method body) flow through here too so `self`-targeted facts can edit
           # `scope.self_type`.
           analyse_rbs_extended_contribution(node, scope)
         end
 
-        # v0.1.1 Track 1 slice 4 — `String#start_with?` /
-        # `#end_with?` / `#include?` against a `Constant<String>`
-        # needle attaches a relational `FactStore::Fact` to the
-        # local on each edge. The receiver's type does NOT
-        # change — Rigor has no "starts-with-X" carrier today —
-        # so the fact carries the predicate semantics for any
-        # downstream consumer that wants to read it (e.g. a
-        # plugin's `prepare(services)` hook in v0.1.x).
-        # Truthy edge: positive polarity. Falsey edge: negative
-        # polarity. Mirrors the equality-predicate fact pattern
-        # already used by `analyse_equality_predicate`.
+        # v0.1.1 Track 1 slice 4 — `String#start_with?` / `#end_with?` / `#include?` against a
+        # `Constant<String>` needle attaches a relational `FactStore::Fact` to the local on
+        # each edge. The receiver's type does NOT change — Rigor has no "starts-with-X" carrier
+        # today — so the fact carries the predicate semantics for any downstream consumer that
+        # wants to read it (e.g. a plugin's `prepare(services)` hook in v0.1.x). Truthy edge:
+        # positive polarity. Falsey edge: negative polarity. Mirrors the equality-predicate fact
+        # pattern already used by `analyse_equality_predicate`.
         STRING_PREDICATE_NAMES = %i[start_with? end_with? include?].freeze
         private_constant :STRING_PREDICATE_NAMES
 
@@ -1080,21 +971,17 @@ module Rigor
           end
         end
 
-        # T3 (template-corpora survey) — `recv.respond_to?(sym)` truthy
-        # edge narrows `recv` non-nil. `nil.respond_to?(m)` is `false`
-        # for every method `m` that `NilClass` does not define, so a
-        # truthy `respond_to?` proves the receiver was not `nil` UNLESS
-        # the queried symbol is one of `NilClass`'s own methods (`:to_s`,
-        # `:inspect`, `:nil?`, …) — `nil` DOES respond to those, so the
-        # truthy edge admits a nil receiver and we narrow nothing.
+        # T3 (template-corpora survey) — `recv.respond_to?(sym)` truthy edge narrows `recv`
+        # non-nil. `nil.respond_to?(m)` is `false` for every method `m` that `NilClass` does not
+        # define, so a truthy `respond_to?` proves the receiver was not `nil` UNLESS the queried
+        # symbol is one of `NilClass`'s own methods (`:to_s`, `:inspect`, `:nil?`, …) — `nil`
+        # DOES respond to those, so the truthy edge admits a nil receiver and we narrow nothing.
         #
-        # Conservative floor: narrow only on a literal `Symbol`/`String`
-        # argument resolved against the RBS environment; a non-literal
-        # symbol, a missing argument, or a symbol that IS in `NilClass`'s
-        # method set declines. The falsey edge is always the no-op
-        # ("does not respond" proves little about the receiver's type).
-        # Narrowing-only: it removes the `nil` constituent and never
-        # promotes a non-nil type.
+        # Conservative floor: narrow only on a literal `Symbol`/`String` argument resolved
+        # against the RBS environment; a non-literal symbol, a missing argument, or a symbol
+        # that IS in `NilClass`'s method set declines. The falsey edge is always the no-op
+        # ("does not respond" proves little about the receiver's type). Narrowing-only: it
+        # removes the `nil` constituent and never promotes a non-nil type.
         def analyse_respond_to_predicate(node, scope)
           return nil if node.block
           return nil if node.arguments.nil? || node.arguments.arguments.size != 1
@@ -1115,12 +1002,11 @@ module Rigor
           [scope.public_send(writer, node.receiver.name, non_nil), scope]
         end
 
-        # True when `nil` responds to `sym` — i.e. `NilClass` (own,
-        # inherited Kernel/BasicObject) defines an instance method named
-        # `sym`. Resolved against the RBS environment; when the lookup
-        # is unavailable the answer is conservatively `true` (decline to
-        # narrow) so an unknown environment never manufactures a false
-        # non-nil narrowing.
+        # True when `nil` responds to `sym` — i.e. `NilClass` (own, inherited
+        # Kernel/BasicObject) defines an instance method named `sym`. Resolved against the RBS
+        # environment; when the lookup is unavailable the answer is conservatively `true`
+        # (decline to narrow) so an unknown environment never manufactures a false non-nil
+        # narrowing.
         def nilclass_method?(sym, scope)
           name = sym.respond_to?(:to_sym) ? sym.to_sym : sym
           return true unless name.is_a?(Symbol)
@@ -1132,23 +1018,20 @@ module Rigor
           true
         end
 
-        # ADR-47 §4-4 (Elixir `tuple_size`/non-empty analogue) — a bare
-        # `arr.empty?` / `arr.any?` / `arr.none?` (no block, no args)
-        # narrows an Array-typed receiver to `non-empty-array[T]` on the
-        # edge that implies "at least one element":
+        # ADR-47 §4-4 (Elixir `tuple_size`/non-empty analogue) — a bare `arr.empty?` /
+        # `arr.any?` / `arr.none?` (no block, no args) narrows an Array-typed receiver to
+        # `non-empty-array[T]` on the edge that implies "at least one element":
         #
         #   - `empty?` → false edge   (the array is NOT empty)
         #   - `any?`   → true  edge   (a truthy element exists ⇒ non-empty)
         #   - `none?`  → false edge   (a truthy element exists ⇒ non-empty)
         #
-        # The opposite edge is the conservative no-op (`any?`/`none?`
-        # falseness does not imply emptiness — the array may hold only
-        # falsey elements; `empty?` truth could narrow to an empty array
-        # but that carrier move is deferred). Only `Nominal[Array, [T]]`
-        # receivers narrow — `Tuple` is already known-length, `Dynamic`
-        # is left alone (gradual guarantee), and a non-Array receiver
-        # (`String#empty?`, `Range#any?`, …) bails so the existing string
-        # / predicate paths still run.
+        # The opposite edge is the conservative no-op (`any?`/`none?` falseness does not imply
+        # emptiness — the array may hold only falsey elements; `empty?` truth could narrow to an
+        # empty array but that carrier move is deferred). Only `Nominal[Array, [T]]` receivers
+        # narrow — `Tuple` is already known-length, `Dynamic` is left alone (gradual
+        # guarantee), and a non-Array receiver (`String#empty?`, `Range#any?`, …) bails so the
+        # existing string / predicate paths still run.
         def analyse_array_emptiness_predicate(node, scope, name)
           return nil if node.block
           return nil unless node.arguments.nil? || node.arguments.arguments.empty?
@@ -1174,9 +1057,9 @@ module Rigor
           end
         end
 
-        # Refines `Array[T]` (and every Array member of a Union) to
-        # `non-empty-array[T]`; returns the input unchanged when nothing
-        # applies, so the caller can detect "no narrowing".
+        # Refines `Array[T]` (and every Array member of a Union) to `non-empty-array[T]`;
+        # returns the input unchanged when nothing applies, so the caller can detect "no
+        # narrowing".
         def narrow_to_non_empty_array(type)
           case type
           when Type::Nominal
@@ -1190,18 +1073,16 @@ module Rigor
           end
         end
 
-        # ADR-47 §4-3 (Elixir `is_map_key/2` analogue) — `h.key?(:foo)`
-        # narrows the receiver on the truthy edge: a `HashShape` whose
-        # `:foo` is an OPTIONAL key has it promoted to REQUIRED, so a
-        # subsequent `h[:foo]` reads the declared value type instead of
-        # `value | nil` (the optionality nil is gone). Sound because key
-        # presence removes only the optionality-injected nil, never the
-        # value's own intrinsic nil (`h = {foo: nil}` keeps `h[:foo]`
-        # nil-typed). The falsey edge is left unchanged — "key absent"
-        # is the conservative no-op. Only literal `Symbol`/`String`
-        # arguments and `LocalVariableReadNode`/`InstanceVariableReadNode`
-        # receivers narrow; everything else (Dynamic, `Nominal[Hash]`,
-        # method-chain receivers, dynamic keys) bails to no narrowing.
+        # ADR-47 §4-3 (Elixir `is_map_key/2` analogue) — `h.key?(:foo)` narrows the receiver on
+        # the truthy edge: a `HashShape` whose `:foo` is an OPTIONAL key has it promoted to
+        # REQUIRED, so a subsequent `h[:foo]` reads the declared value type instead of `value |
+        # nil` (the optionality nil is gone). Sound because key presence removes only the
+        # optionality-injected nil, never the value's own intrinsic nil (`h = {foo: nil}` keeps
+        # `h[:foo]` nil-typed). The falsey edge is left unchanged — "key absent" is the
+        # conservative no-op. Only literal `Symbol`/`String` arguments and
+        # `LocalVariableReadNode`/`InstanceVariableReadNode` receivers narrow; everything else
+        # (Dynamic, `Nominal[Hash]`, method-chain receivers, dynamic keys) bails to no
+        # narrowing.
         def analyse_key_presence_predicate(node, scope)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
@@ -1222,10 +1103,9 @@ module Rigor
           return nil if current.nil?
 
           truthy = narrow_hash_key_present(current, key)
-          # §4-3 false edge — `h.key?(:foo)` being false proves `:foo` is
-          # absent, so on that edge `h[:foo]` reads `nil`. Remove the
-          # (optional) key from the shape; a required key makes the false
-          # edge dead and an unknown key is already nil, both no-ops.
+          # §4-3 false edge — `h.key?(:foo)` being false proves `:foo` is absent, so on that
+          # edge `h[:foo]` reads `nil`. Remove the (optional) key from the shape; a required
+          # key makes the false edge dead and an unknown key is already nil, both no-ops.
           falsey = narrow_hash_key_absent(current, key)
           return nil if truthy.equal?(current) && falsey.equal?(current) # predicate is opaque
 
@@ -1241,9 +1121,9 @@ module Rigor
           end
         end
 
-        # Promotes `key` from optional to required across a HashShape (or
-        # every HashShape member of a Union). Returns the input unchanged
-        # when nothing applies, so the caller can detect "no narrowing".
+        # Promotes `key` from optional to required across a HashShape (or every HashShape
+        # member of a Union). Returns the input unchanged when nothing applies, so the caller
+        # can detect "no narrowing".
         def narrow_hash_key_present(type, key)
           case type
           when Type::HashShape
@@ -1268,12 +1148,11 @@ module Rigor
           )
         end
 
-        # §4-3 false edge — drops `key` from a HashShape (or every HashShape
-        # member of a Union) so the proven-absent key reads `nil`. Returns
-        # the input unchanged when nothing applies (caller detects "no
-        # narrowing"). Only an *optional* present key is removed: a required
-        # key makes `key?` always true (the false edge is dead, leave the
-        # shape opaque) and a key absent from `pairs` already reads `nil`.
+        # §4-3 false edge — drops `key` from a HashShape (or every HashShape member of a Union)
+        # so the proven-absent key reads `nil`. Returns the input unchanged when nothing
+        # applies (caller detects "no narrowing"). Only an *optional* present key is removed: a
+        # required key makes `key?` always true (the false edge is dead, leave the shape opaque)
+        # and a key absent from `pairs` already reads `nil`.
         def narrow_hash_key_absent(type, key)
           case type
           when Type::HashShape
@@ -1298,27 +1177,21 @@ module Rigor
           )
         end
 
-        # Survey item (b): `/regex/ =~ str` and `str =~ /regex/`
-        # bind the regex match-data globals on each edge.
+        # Survey item (b): `/regex/ =~ str` and `str =~ /regex/` bind the regex match-data
+        # globals on each edge.
         #
-        # - Truthy edge (`=~` returned an Integer position — the
-        #   match succeeded): `$~` to `Nominal[MatchData]`; `$&`
-        #   and `$1..$N` (where N is the number of capture groups
-        #   in the regex source) to `Nominal[String]`. This is the
-        #   same optimistic-narrowing shape the existing
-        #   `analyse_match_write` uses for named captures inside
-        #   `if /(?<x>...)/ =~ str` — optional groups in the
-        #   regex source (`(\d+)?`) would bind `$N` to `nil` at
-        #   runtime, but the floor here matches the common idiom
-        #   (required captures) and lets `unless /(\d+)/ =~ s;
-        #   raise; end; $1.to_i` resolve cleanly.
-        # - Falsey edge (`=~` returned nil — no match): `$~` and
-        #   every numbered / back-reference global bound to
-        #   `Constant<nil>`.
+        # - Truthy edge (`=~` returned an Integer position — the match succeeded): `$~` to
+        #   `Nominal[MatchData]`; `$&` and `$1..$N` (where N is the number of capture groups in
+        #   the regex source) to `Nominal[String]`. This is the same optimistic-narrowing shape
+        #   the existing `analyse_match_write` uses for named captures inside `if /(?<x>...)/
+        #   =~ str` — optional groups in the regex source (`(\d+)?`) would bind `$N` to `nil`
+        #   at runtime, but the floor here matches the common idiom (required captures) and
+        #   lets `unless /(\d+)/ =~ s; raise; end; $1.to_i` resolve cleanly.
+        # - Falsey edge (`=~` returned nil — no match): `$~` and every numbered / back-reference
+        #   global bound to `Constant<nil>`.
         #
-        # Returns nil (no narrowing) when the receiver / argument
-        # pair does not include a `RegularExpressionNode` literal
-        # we can count.
+        # Returns nil (no narrowing) when the receiver / argument pair does not include a
+        # `RegularExpressionNode` literal we can count.
         def analyse_regex_match_predicate(node, scope)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
@@ -1343,14 +1216,12 @@ module Rigor
         REGEX_MATCH_GLOBALS = %i[$~ $& $` $' $+].freeze
         private_constant :REGEX_MATCH_GLOBALS
 
-        # `unconditional` is the Set of 1-based numbered-capture
-        # indices whose group is guaranteed to participate in any
-        # successful match (no optional quantifier on the group or
-        # an ancestor, no alternation in the pattern). Those `$N`
-        # are bound to `String`; every other numbered group present
-        # in the pattern stays `String | nil` on both edges (a
-        # truthy match leaves an optional group nil at runtime), so
-        # we do not narrow it on the truthy edge.
+        # `unconditional` is the Set of 1-based numbered-capture indices whose group is
+        # guaranteed to participate in any successful match (no optional quantifier on the
+        # group or an ancestor, no alternation in the pattern). Those `$N` are bound to
+        # `String`; every other numbered group present in the pattern stays `String | nil` on
+        # both edges (a truthy match leaves an optional group nil at runtime), so we do not
+        # narrow it on the truthy edge.
         def regex_match_predicate_scopes(scope, unconditional)
           string_t = Type::Combinator.nominal_of("String")
           match_data_t = Type::Combinator.nominal_of("MatchData")
@@ -1374,31 +1245,24 @@ module Rigor
           [truthy, falsey]
         end
 
-        # Returns the Set of 1-based numbered-capture indices that
-        # are UNCONDITIONAL in `source`: present on every successful
-        # match because no optional quantifier (`?`, `*`, `{0,…}`)
-        # applies to the group or any ancestor group, and the
-        # pattern contains no alternation (`|`). Optional and
-        # alternation-reachable groups are excluded — at runtime `$N`
-        # is `nil` for them even when the overall match succeeds, so
-        # narrowing them to non-nil `String` would be unsound. The
-        # walker is intentionally light (char scan, not a regex-AST
-        # parse): backslash escapes are skipped; `(?:…)`, lookahead
-        # `(?=…)`/`(?!…)`, and lookbehind `(?<=…)`/`(?<!…)` do not
-        # capture; named groups `(?<name>…)` do. Conservatism is
-        # one-directional — when in doubt a group is treated as
-        # conditional (dropped from the Set), never the reverse.
+        # Returns the Set of 1-based numbered-capture indices that are UNCONDITIONAL in
+        # `source`: present on every successful match because no optional quantifier (`?`,
+        # `*`, `{0,…}`) applies to the group or any ancestor group, and the pattern contains no
+        # alternation (`|`). Optional and alternation-reachable groups are excluded — at
+        # runtime `$N` is `nil` for them even when the overall match succeeds, so narrowing
+        # them to non-nil `String` would be unsound. The walker is intentionally light (char
+        # scan, not a regex-AST parse): backslash escapes are skipped; `(?:…)`, lookahead
+        # `(?=…)`/`(?!…)`, and lookbehind `(?<=…)`/`(?<!…)` do not capture; named groups
+        # `(?<name>…)` do. Conservatism is one-directional — when in doubt a group is treated
+        # as conditional (dropped from the Set), never the reverse.
         def unconditional_capture_groups(source)
-          # `unconditional` collects every capturing index; a group is
-          # later removed (with its whole subtree) when it is optionally
-          # quantified, nested under an optional ancestor, or sits in an
-          # alternation branch. `stack` holds one frame per open group
-          # (plus a virtual root frame for the top level) as
-          # `[group_index_or_nil, descendant_indices, alternated?]`.
-          # A `|` marks the CURRENT group's frame alternated — its
-          # branches are mutually exclusive, so its descendant captures
-          # may be absent on a successful match; the group itself still
-          # participates. Closing a frame rolls its subtree up to the
+          # `unconditional` collects every capturing index; a group is later removed (with its
+          # whole subtree) when it is optionally quantified, nested under an optional ancestor,
+          # or sits in an alternation branch. `stack` holds one frame per open group (plus a
+          # virtual root frame for the top level) as `[group_index_or_nil, descendant_indices,
+          # alternated?]`. A `|` marks the CURRENT group's frame alternated — its branches are
+          # mutually exclusive, so its descendant captures may be absent on a successful match;
+          # the group itself still participates. Closing a frame rolls its subtree up to the
           # parent so an optional / alternated ancestor disqualifies it.
           state = { unconditional: Set.new, stack: [[nil, [], false]], group_index: 0 }
           pos = 0
@@ -1422,8 +1286,8 @@ module Rigor
         end
 
         # Updates the walk `state` at a group-relevant char during
-        # {#unconditional_capture_groups}: `(` pushes a frame, `)` pops
-        # and resolves it, `|` flags the current frame as alternated.
+        # {#unconditional_capture_groups}: `(` pushes a frame, `)` pops and resolves it, `|`
+        # flags the current frame as alternated.
         def scan_group_char(source, pos, chr, state)
           case chr
           when "("
@@ -1440,11 +1304,10 @@ module Rigor
           end
         end
 
-        # Resolves a closed (or virtual-root) group frame: its subtree is
-        # its own index plus every descendant index. The subtree is
-        # disqualified when the group is optionally quantified or its
-        # branches are alternated (only the descendants in that case —
-        # but a self subtree always keeps its own index unless optional).
+        # Resolves a closed (or virtual-root) group frame: its subtree is its own index plus
+        # every descendant index. The subtree is disqualified when the group is optionally
+        # quantified or its branches are alternated (only the descendants in that case — but a
+        # self subtree always keeps its own index unless optional).
         def finalize_frame(state, frame, optional:)
           idx, descendants, alternated = frame
           subtree = descendants.dup
@@ -1456,11 +1319,10 @@ module Rigor
           state[:stack].last && state[:stack].last[1].concat(subtree)
         end
 
-        # True when the group whose closing paren is at `source[pos]`
-        # is followed by a quantifier that permits zero repetitions
-        # (`?`, `*`, `{0…}`). `+` and `{1,…}` do NOT make a group
-        # optional. A lazy/possessive suffix (`*?`, `*+`) is still
-        # zero-permitting on the base quantifier.
+        # True when the group whose closing paren is at `source[pos]` is followed by a
+        # quantifier that permits zero repetitions (`?`, `*`, `{0…}`). `+` and `{1,…}` do NOT
+        # make a group optional. A lazy/possessive suffix (`*?`, `*+`) is still zero-permitting
+        # on the base quantifier.
         def next_quantifier_optional?(source, pos)
           case source[pos]
           when "?", "*" then true
@@ -1499,9 +1361,8 @@ module Rigor
           end
         end
 
-        # `:positive?` / `:negative?` / `:zero?` / `:nonzero?` are
-        # zero-arg predicates on `Numeric`. We model them as
-        # comparisons against the literal 0 so the existing range
+        # `:positive?` / `:negative?` / `:zero?` / `:nonzero?` are zero-arg predicates on
+        # `Numeric`. We model them as comparisons against the literal 0 so the existing range
         # narrowing handles them uniformly.
         ZERO_CLASS_PREDICATE_RULES = Ractor.make_shareable({
                                                              positive?: { truthy: [:>, 0], falsey: [:<=, 0] },
@@ -1534,11 +1395,9 @@ module Rigor
           end
         end
 
-        # `x.between?(a, b)` truthy edge narrows to
-        # `narrow_integer_comparison(>=, a)` ∩
-        # `narrow_integer_comparison(<=, b)`. The falsey edge is left
-        # unchanged because the complement is a two-piece domain
-        # (`x < a || x > b`) that the lattice cannot express
+        # `x.between?(a, b)` truthy edge narrows to `narrow_integer_comparison(>=, a)` ∩
+        # `narrow_integer_comparison(<=, b)`. The falsey edge is left unchanged because the
+        # complement is a two-piece domain (`x < a || x > b`) that the lattice cannot express
         # precisely. `a` and `b` MUST both be integer literals.
         def analyse_between_predicate(node, scope)
           return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
@@ -1559,9 +1418,8 @@ module Rigor
           [scope.with_local(local_name, truthy), scope]
         end
 
-        # Helper for {.narrow_integer_not_equal}. Only adjusts when the
-        # value sits exactly on one endpoint, so the result stays
-        # contiguous; otherwise the input range is preserved.
+        # Helper for {.narrow_integer_not_equal}. Only adjusts when the value sits exactly on
+        # one endpoint, so the result stays contiguous; otherwise the input range is preserved.
         def narrow_integer_range_not_equal(range, value)
           return range if range.lower > value || range.upper < value
           return Type::Combinator.bot if single_point_range_equal?(range, value)
@@ -1607,9 +1465,8 @@ module Rigor
         # Comparison predicate analyser. Recognised shapes:
         #   x  <  Int        x  <=  Int        x  >  Int        x  >=  Int
         #   Int <  x         Int <=  x         Int >  x         Int >=  x
-        # The reversed (literal-on-left) form is normalised by
-        # transposing the operator so the receiver-local always
-        # appears on the left of the rule.
+        # The reversed (literal-on-left) form is normalised by transposing the operator so the
+        # receiver-local always appears on the left of the rule.
         INVERT_COMPARISON_OP = { :< => :>=, :<= => :>, :> => :<=, :>= => :< }.freeze
         REVERSE_COMPARISON_OP = { :< => :>, :<= => :>=, :> => :<, :>= => :<= }.freeze
         private_constant :INVERT_COMPARISON_OP, :REVERSE_COMPARISON_OP
@@ -1778,12 +1635,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 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".
+        # `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
+        # 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".
         def analyse_class_predicate(node, scope, exact:)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
@@ -1791,16 +1646,12 @@ module Rigor
           bare_name = static_class_name(node.arguments.arguments.first)
           return nil if bare_name.nil?
 
-          # Resolve `bare_name` through the lexical-scope chain
-          # so a name shadowed by the current class / enclosing
-          # module wins over the top-level constant. Mirrors
-          # Ruby's `Module.nesting`-driven constant lookup. The
-          # canonical motivating case: inside
-          # `Rigor::Type::Singleton#==`, `is_a?(Singleton)`
-          # should resolve to `Rigor::Type::Singleton`, not the
-          # top-level stdlib `Singleton` mixin (which would
-          # surface as a spurious `undefined-method` on
-          # subsequent `other.class_name` calls).
+          # Resolve `bare_name` through the lexical-scope chain so a name shadowed by the
+          # current class / enclosing module wins over the top-level constant. Mirrors Ruby's
+          # `Module.nesting`-driven constant lookup. The canonical motivating case: inside
+          # `Rigor::Type::Singleton#==`, `is_a?(Singleton)` should resolve to
+          # `Rigor::Type::Singleton`, not the top-level stdlib `Singleton` mixin (which would
+          # surface as a spurious `undefined-method` on subsequent `other.class_name` calls).
           class_name = resolve_class_name_lexically(bare_name, scope)
 
           case node.receiver
@@ -1818,27 +1669,20 @@ 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
-        # `<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
+        # Stable single-hop method-chain narrowing (ROADMAP § Future cycles — "Method-call
+        # receiver narrowing across stable receivers"). 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 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 `StatementEvaluator#eval_call`'s
-        # invalidation step). The Law of Demeter justifies the
-        # single-hop restriction: a single-hop chain is the
-        # idiomatic Ruby shape where re-evaluation soundness is
-        # the strongest.
+        # Heuristic-by-design (ROADMAP § "Soundness gap"): 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
+        # `StatementEvaluator#eval_call`'s invalidation step). The Law of Demeter justifies the
+        # single-hop restriction: a single-hop chain is the idiomatic Ruby shape where
+        # re-evaluation soundness is the strongest.
         def analyse_class_predicate_on_chain(node, scope, class_name, exact)
           address = stable_chain_address(node.receiver)
           return nil if address.nil?
@@ -1855,12 +1699,10 @@ module Rigor
           ]
         end
 
-        # Returns `[receiver_kind, receiver_name, method_name]`
-        # iff `chain_call` is a stable single-hop chain whose
-        # root is a local / ivar read and whose own call shape
-        # has no positional arguments and no block. Other shapes
-        # (multi-hop, args, block, method-defined-on-arbitrary-
-        # receiver) lose stability for one of the reasons
+        # Returns `[receiver_kind, receiver_name, method_name]` iff `chain_call` is a stable
+        # single-hop chain whose root is a local / ivar read and whose own call shape has no
+        # positional arguments and no block. Other shapes (multi-hop, args, block,
+        # method-defined-on-arbitrary-receiver) lose stability for one of the reasons
         # enumerated in the slice's design notes.
         def stable_chain_address(chain_call)
           return nil unless chain_call.is_a?(Prism::CallNode)
@@ -1877,13 +1719,10 @@ module Rigor
           end
         end
 
-        # Walks the lexical-nesting chain derived from
-        # `scope.self_type` and returns the first
-        # `<prefix>::<bare_name>` (or bare `<bare_name>` at the
-        # top level) that the environment recognises. Falls back
-        # to `bare_name` itself when nothing in the chain
-        # resolves; the downstream `narrow_class` then yields
-        # the conservative answer for unknown receivers.
+        # Walks the lexical-nesting chain derived from `scope.self_type` and returns the first
+        # `<prefix>::<bare_name>` (or bare `<bare_name>` at the top level) that the environment
+        # recognises. Falls back to `bare_name` itself when nothing in the chain resolves; the
+        # downstream `narrow_class` then yields the conservative answer for unknown receivers.
         def resolve_class_name_lexically(bare_name, scope)
           return bare_name if bare_name.include?("::") # Already qualified.
 
@@ -1895,9 +1734,8 @@ module Rigor
           bare_name
         end
 
-        # Combines the environment's RBS-known set with the
-        # scope's in-source `discovered_classes` table so a
-        # lexical-nesting candidate matches a class the project
+        # Combines the environment's RBS-known set with the scope's in-source
+        # `discovered_classes` table so a lexical-nesting candidate matches a class the project
         # declares but has no RBS for.
         def class_known_to_scope?(scope, candidate)
           return true if scope.environment.class_known?(candidate)
@@ -1905,14 +1743,11 @@ module Rigor
           scope.discovered_classes.key?(candidate)
         end
 
-        # Approximates `Module.nesting` from the inferable
-        # `self_type`. Today's implementation handles the common
-        # case: when the surrounding method is a regular
-        # instance method (`self_type = Nominal[T]`) or a
-        # class-body / singleton (`self_type = Singleton[T]`),
-        # the chain is `T`'s namespace path — `Foo::Bar::Baz`
-        # → `["Foo::Bar::Baz", "Foo::Bar", "Foo"]`. Returns an
-        # empty array when `self_type` is unknown.
+        # Approximates `Module.nesting` from the inferable `self_type`. Today's implementation
+        # handles the common case: when the surrounding method is a regular instance method
+        # (`self_type = Nominal[T]`) or a class-body / singleton (`self_type = Singleton[T]`),
+        # the chain is `T`'s namespace path — `Foo::Bar::Baz` → `["Foo::Bar::Baz", "Foo::Bar",
+        # "Foo"]`. Returns an empty array when `self_type` is unknown.
         def lexical_nesting_for(scope)
           self_type = scope.self_type
           base = case self_type
@@ -1937,33 +1772,24 @@ module Rigor
           ]
         end
 
-        # Slice 7 phase 4 — `===`-narrowing. The case-equality
-        # predicate `<receiver> === local` is the operator that
-        # backs Ruby's `case`/`when` dispatch. Three receiver
-        # shapes produce sound narrowing rules:
+        # Slice 7 phase 4 — `===`-narrowing. The case-equality predicate `<receiver> === local`
+        # is the operator that backs Ruby's `case`/`when` dispatch. Three receiver shapes
+        # produce sound narrowing rules:
         #
-        # - **Class / Module receiver**: `Foo === x` is
-        #   isomorphic to `x.is_a?(Foo)` (the default behaviour
-        #   of `Module#===`). Reuse `class_predicate_scopes` so
-        #   the truthy edge narrows down to `Foo` and the falsey
-        #   edge subtracts `Foo` from a union.
-        # - **Range literal receiver** (`(1..10) === x`): the
-        #   default `Range#===` includes `x` iff the endpoints
-        #   compare it. We conservatively narrow `x` to
-        #   `Numeric` for integer-endpoint ranges and to
-        #   `String` for string-endpoint ranges; other endpoint
+        # - **Class / Module receiver**: `Foo === x` is isomorphic to `x.is_a?(Foo)` (the
+        #   default behaviour of `Module#===`). Reuse `class_predicate_scopes` so the truthy
+        #   edge narrows down to `Foo` and the falsey edge subtracts `Foo` from a union.
+        # - **Range literal receiver** (`(1..10) === x`): the default `Range#===` includes `x`
+        #   iff the endpoints compare it. We conservatively narrow `x` to `Numeric` for
+        #   integer-endpoint ranges and to `String` for string-endpoint ranges; other endpoint
         #   types fall through.
-        # - **Regexp literal receiver** (`/foo/ === x`): the
-        #   match operator coerces `x` to a String, so the
-        #   truthy edge narrows `x` to `String`. The falsey
-        #   edge keeps the entry type unchanged because
-        #   `Regexp#===` returns false for non-Strings AND for
-        #   Strings that simply do not match.
+        # - **Regexp literal receiver** (`/foo/ === x`): the match operator coerces `x` to a
+        #   String, so the truthy edge narrows `x` to `String`. The falsey edge keeps the entry
+        #   type unchanged because `Regexp#===` returns false for non-Strings AND for Strings
+        #   that simply do not match.
         #
-        # Anything else — non-local LHS argument, dynamic
-        # receiver, custom `===` method — falls through to
-        # the no-narrowing branch (nil), preserving the
-        # entry scope on both edges.
+        # Anything else — non-local LHS argument, dynamic receiver, custom `===` method — falls
+        # through to the no-narrowing branch (nil), preserving the entry scope on both edges.
         def analyse_case_equality_predicate(node, scope)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
@@ -1980,14 +1806,12 @@ module Rigor
           end
         end
 
-        # `Class === <local/ivar>.<method>` — the case-equality counterpart
-        # of {.analyse_class_predicate_on_chain}. The `open3` idiom
-        # `if Hash === cmd.last` narrows `cmd.last` to the class inside the
-        # branch, recorded as a single-hop method-chain narrowing keyed on
-        # the chain address (same stability rules as `is_a?` on a chain).
-        # Only static class/module receivers narrow here — the Range /
-        # Regexp literal receivers (`(1..10) === x.foo`) are not a common
-        # method-chain shape and stay deferred.
+        # `Class === <local/ivar>.<method>` — the case-equality counterpart of
+        # {.analyse_class_predicate_on_chain}. The `open3` idiom `if Hash === cmd.last` narrows
+        # `cmd.last` to the class inside the branch, recorded as a single-hop method-chain
+        # narrowing keyed on the chain address (same stability rules as `is_a?` on a chain).
+        # Only static class/module receivers narrow here — the Range / Regexp literal receivers
+        # (`(1..10) === x.foo`) are not a common method-chain shape and stay deferred.
         def analyse_case_equality_on_chain(receiver, chain_arg, scope)
           class_name = static_class_name(receiver)
           return nil if class_name.nil?
@@ -2021,14 +1845,11 @@ module Rigor
           ]
         end
 
-        # Maps a case-equality literal receiver to the class
-        # whose membership is implied by the truthy edge.
-        # `Prism::ParenthesesNode` wrappers are transparently
-        # unwrapped (`(1..10) === x` is parsed with the range
-        # inside parentheses).  Range literals: integer
-        # endpoints → `Numeric`; string endpoints → `String`.
-        # Regexp literals → `String`. Other shapes return nil
-        # so the caller falls through.
+        # Maps a case-equality literal receiver to the class whose membership is implied by the
+        # truthy edge. `Prism::ParenthesesNode` wrappers are transparently unwrapped (`(1..10)
+        # === x` is parsed with the range inside parentheses).  Range literals: integer
+        # endpoints → `Numeric`; string endpoints → `String`. Regexp literals → `String`. Other
+        # shapes return nil so the caller falls through.
         def case_equality_target_class(receiver)
           receiver = unwrap_parens(receiver)
           case receiver
@@ -2045,34 +1866,24 @@ module Rigor
           node
         end
 
-        # Slice 4b-1 (ADR-7 § "Slice 4-A/4-B") — single-point
-        # RBS::Extended contribution analyser. Replaces the
-        # earlier sibling pair (`analyse_rbs_extended_predicate`
-        # + `analyse_rbs_extended_assert_if`) with one path that
-        # routes through `RbsExtended.read_flow_contribution` and
-        # `Rigor::FlowContribution::Merger.merge`. The bundle's
-        # `truthy_facts` slot already includes both the
-        # `predicate-if-true` and `assert-if-true` Facts (slice
-        # 4a routing closed the v0.0.9 imperfection); the
-        # `falsey_facts` slot mirrors that. The merger composes
-        # any future plugin contribution at the same site
-        # alongside the RBS::Extended bundle without changing
-        # this analyser.
+        # Slice 4b-1 (ADR-7 § "Slice 4-A/4-B") — single-point RBS::Extended contribution
+        # analyser. Replaces the earlier sibling pair (`analyse_rbs_extended_predicate` +
+        # `analyse_rbs_extended_assert_if`) with one path that routes through
+        # `RbsExtended.read_flow_contribution` and `Rigor::FlowContribution::Merger.merge`. The
+        # bundle's `truthy_facts` slot already includes both the `predicate-if-true` and
+        # `assert-if-true` Facts (slice 4a routing closed the v0.0.9 imperfection); the
+        # `falsey_facts` slot mirrors that. The merger composes any future plugin contribution
+        # at the same site alongside the RBS::Extended bundle without changing this analyser.
         #
-        # Conservative envelope (carried over from the previous
-        # implementation):
-        # - Receiver type must be `Type::Nominal`,
-        #   `Type::Singleton`, or `Type::Constant`.
+        # Conservative envelope (carried over from the previous implementation):
+        # - Receiver type must be `Type::Nominal`, `Type::Singleton`, or `Type::Constant`.
         # - The method must be present in the loader.
-        # - 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.
+        # - 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.
         def analyse_rbs_extended_contribution(node, scope)
           method_def = resolve_rbs_extended_method(node, scope)
           return nil if method_def.nil?
@@ -2113,10 +1924,9 @@ module Rigor
           target_scope.with_local(local_name, narrowed)
         end
 
-        # v0.1.1 Track 1 slice 3 — `target_kind == :self` facts
-        # (`predicate-if-true self is T`, `predicate-if-false
-        # self is T`) narrow whichever scope binding is bound to
-        # the call's receiver. Four receiver shapes participate:
+        # v0.1.1 Track 1 slice 3 — `target_kind == :self` facts (`predicate-if-true self is T`,
+        # `predicate-if-false self is T`) narrow whichever scope binding is bound to the call's
+        # receiver. Four receiver shapes participate:
         #
         #   `recv.method?` where recv is...
         #   - `LocalVariableReadNode`            -> narrow that local
@@ -2125,8 +1935,8 @@ module Rigor
         #   - nil (implicit self call inside a method body)
         #                                        -> narrow `self_type`
         #
-        # Other receiver shapes (method chains, expressions) have
-        # no scope binding to narrow against and fall through.
+        # Other receiver shapes (method chains, expressions) have no scope binding to narrow
+        # against and fall through.
         def apply_self_fact(fact, receiver_node, entry_scope, target_scope)
           case receiver_node
           when nil, Prism::SelfNode
@@ -2152,11 +1962,9 @@ module Rigor
           end
         end
 
-        # Resolves a Fact's target node. Mirrors the earlier
-        # `effect_target_node` helper but reads from the
-        # canonical Fact carrier; `:self` routes to the call
-        # receiver, otherwise we look up the matching
-        # positional argument by parameter name.
+        # Resolves a Fact's target node. Mirrors the earlier `effect_target_node` helper but
+        # reads from the canonical Fact carrier; `:self` routes to the call receiver, otherwise
+        # we look up the matching positional argument by parameter name.
         def fact_target_node(fact, call_node, method_def)
           if fact.target_kind == :self
             call_node.receiver
@@ -2182,9 +1990,8 @@ module Rigor
           nil
         end
 
-        # Implicit self call (`admin?` with no receiver inside an
-        # instance method body) — read the method definition from
-        # `scope.self_type` per v0.1.1 Track 1 slice 3.
+        # Implicit self call (`admin?` with no receiver inside an instance method body) — read
+        # the method definition from `scope.self_type` per v0.1.1 Track 1 slice 3.
         def receiver_type_for_resolve(node, scope)
           node.receiver.nil? ? scope.self_type : scope.type_of(node.receiver)
         end
@@ -2209,11 +2016,9 @@ module Rigor
           nil
         end
 
-        # Maps the effect's target parameter name to the call
-        # site argument by inspecting the selected overload's
-        # required-positional parameter list. Returns the Prism
-        # arg node at that position, or nil when the overload
-        # shape does not allow a precise match.
+        # Maps the effect's target parameter name to the call site argument by inspecting the
+        # selected overload's required-positional parameter list. Returns the Prism arg node at
+        # that position, or nil when the overload shape does not allow a precise match.
         def lookup_positional_arg(call_node, method_def, target_name)
           arguments = call_node.arguments&.arguments || []
           method_def.method_types.each do |mt|
@@ -2224,18 +2029,13 @@ module Rigor
           nil
         end
 
-        # Slice 7 phase 5 — case/when accumulator. Walks each
-        # `when` condition, computes the narrowed type for the
-        # subject as if `condition === subject`, and accumulates
-        # them. The body's narrowed type is the union across
-        # all conditions; the falsey type is the running result
-        # after subtracting every condition's class. Conditions
-        # whose shape we cannot statically classify are treated
-        # as "no narrowing": the body falls back to the union of
-        # what we did learn (or the entry type when nothing
-        # learned), and the falsey edge is the entry type
-        # (because we cannot prove the unknown condition didn't
-        # match).
+        # Slice 7 phase 5 — case/when accumulator. Walks each `when` condition, computes the
+        # narrowed type for the subject as if `condition === subject`, and accumulates them.
+        # The body's narrowed type is the union across all conditions; the falsey type is the
+        # running result after subtracting every condition's class. Conditions whose shape we
+        # cannot statically classify are treated as "no narrowing": the body falls back to the
+        # union of what we did learn (or the entry type when nothing learned), and the falsey
+        # edge is the entry type (because we cannot prove the unknown condition didn't match).
         def accumulate_case_when_scopes(scope, local_name, current, conditions)
           truthy_members = []
           falsey_type = current
@@ -2259,9 +2059,9 @@ module Rigor
           ]
         end
 
-        # Per-condition rule. Returns `nil` when the condition shape
-        # is not recognised (caller marks `fully_narrowable = false`),
-        # or `{truthy:, falsey:, fully_narrowable:}` when it is.
+        # Per-condition rule. Returns `nil` when the condition shape is not recognised (caller
+        # marks `fully_narrowable = false`), or `{truthy:, falsey:, fully_narrowable:}` when it
+        # is.
         def apply_case_when_condition(scope, current, condition, falsey_acc)
           int_range = case_equality_integer_range(condition)
           return integer_range_when_result(current, int_range, falsey_acc) if int_range && integer_rooted_type?(current)
@@ -2283,11 +2083,10 @@ module Rigor
         end
 
         def integer_literal_when_result(current, value, falsey_acc)
-          # `case n when k` is `k === n` which for Integer is value
-          # equality. The truthy edge collapses the local to
-          # `Constant[k]`; the falsey edge tightens via
-          # `narrow_integer_not_equal` (only effective when k sits
-          # at one endpoint of the current range).
+          # `case n when k` is `k === n` which for Integer is value equality. The truthy edge
+          # collapses the local to `Constant[k]`; the falsey edge tightens via
+          # `narrow_integer_not_equal` (only effective when k sits at one endpoint of the
+          # current range).
           {
             truthy: narrow_integer_equal(current, value),
             falsey: narrow_integer_not_equal(falsey_acc, value),
@@ -2301,10 +2100,9 @@ module Rigor
             narrow_integer_comparison(current, :>=, low),
             :<=, high
           )
-          # The falsey edge of `n in [a, b]` is two-piece; we cannot
-          # express the complement precisely with a single carrier,
-          # so keep the accumulator unchanged. `fully_narrowable: false`
-          # forces the else-branch to see `current` (the unmodified
+          # The falsey edge of `n in [a, b]` is two-piece; we cannot express the complement
+          # precisely with a single carrier, so keep the accumulator unchanged.
+          # `fully_narrowable: false` forces the else-branch to see `current` (the unmodified
           # entry type), which mirrors `between?` falsey behaviour.
           { truthy: truthy, falsey: falsey_acc, fully_narrowable: false }
         end
@@ -2317,12 +2115,10 @@ module Rigor
           }
         end
 
-        # Returns `[low, high]` for a `Prism::RangeNode` whose
-        # endpoints are both `Prism::IntegerNode` literals, with
-        # `..`/`...` exclusivity respected. Open-ended ranges use
-        # the symbolic infinities so the existing comparison
-        # narrowing tier handles them. Returns `nil` for any other
-        # shape (Float endpoints, String endpoints, dynamic
+        # Returns `[low, high]` for a `Prism::RangeNode` whose endpoints are both
+        # `Prism::IntegerNode` literals, with `..`/`...` exclusivity respected. Open-ended
+        # ranges use the symbolic infinities so the existing comparison narrowing tier handles
+        # them. Returns `nil` for any other shape (Float endpoints, String endpoints, dynamic
         # expressions).
         def case_equality_integer_range(condition)
           condition = unwrap_parens(condition)
@@ -2369,9 +2165,8 @@ module Rigor
           node.is_a?(Prism::StringNode)
         end
 
-        # Walks a constant-reference subtree (`Prism::ConstantReadNode`,
-        # `Prism::ConstantPathNode`) and renders its qualified name.
-        # Returns nil for any non-constant argument shape so the
+        # Walks a constant-reference subtree (`Prism::ConstantReadNode`, `Prism::ConstantPathNode`)
+        # and renders its qualified name. Returns nil for any non-constant argument shape so the
         # caller can fall through.
         def static_class_name(node)
           case node
@@ -2390,11 +2185,10 @@ module Rigor
 
         # ----- narrow_class / narrow_not_class helpers -----
 
-        # Polarity-aware dispatch table for {.narrow_class} /
-        # {.narrow_not_class}. Avoids duplicating the per-carrier
-        # case statement and keeps each public surface a thin
-        # delegate; the per-carrier helpers know which polarity to
-        # apply by looking at `polarity:`.
+        # Polarity-aware dispatch table for {.narrow_class} / {.narrow_not_class}. Avoids
+        # duplicating the per-carrier case statement and keeps each public surface a thin
+        # delegate; the per-carrier helpers know which polarity to apply by looking at
+        # `polarity:`.
         def narrow_class_dispatch(type, class_name, context)
           case type
           when Type::Constant then narrow_constant_class(type, class_name, context)
@@ -2459,15 +2253,12 @@ module Rigor
           subclass_of?(rigor_class, class_name, context) ? Type::Combinator.bot : constant
         end
 
-        # Narrow a Nominal under `is_a?(class_name)`: when the
-        # nominal's class is already a subclass of `class_name`
-        # (or matches under `exact: true`) preserve it; when
-        # `class_name` is a subclass of the nominal's class
-        # (`Nominal[Numeric]` under `is_a?(Integer)`) narrow DOWN
-        # to `Nominal[class_name]`; otherwise (disjoint hierarchies
-        # under `is_a?`, mismatch under `instance_of?`) collapse to
-        # `Bot`. Conservative when the analyzer environment cannot
-        # resolve either class.
+        # Narrow a Nominal under `is_a?(class_name)`: when the nominal's class is already a
+        # subclass of `class_name` (or matches under `exact: true`) preserve it; when
+        # `class_name` is a subclass of the nominal's class (`Nominal[Numeric]` under
+        # `is_a?(Integer)`) narrow DOWN to `Nominal[class_name]`; otherwise (disjoint
+        # hierarchies under `is_a?`, mismatch under `instance_of?`) collapse to `Bot`.
+        # Conservative when the analyzer environment cannot resolve either class.
         def narrow_nominal_to_class(nominal, class_name, context)
           return nominal if nominal.class_name == class_name
           return Type::Combinator.bot if context.exact
@@ -2498,11 +2289,10 @@ module Rigor
           subclass_of?(projected_class, class_name, context) ? Type::Combinator.bot : shape
         end
 
-        # `Singleton[Foo]` is the *class object* `Foo`, an instance of
-        # `Class` (which is a subclass of `Module`). Asking
-        # `Foo.is_a?(Class)` returns true; `Foo.is_a?(Foo)` returns
-        # false unless `Foo` is `Class` itself. We approximate this
-        # by treating singletons uniformly as `Class` instances.
+        # `Singleton[Foo]` is the *class object* `Foo`, an instance of `Class` (which is a
+        # subclass of `Module`). Asking `Foo.is_a?(Class)` returns true; `Foo.is_a?(Foo)`
+        # returns false unless `Foo` is `Class` itself. We approximate this by treating
+        # singletons uniformly as `Class` instances.
         def narrow_singleton_to_class(singleton, class_name, context)
           subclass_of?("Class", class_name, context) ? singleton : Type::Combinator.bot
         end
@@ -2511,8 +2301,8 @@ module Rigor
           subclass_of?("Class", class_name, context) ? Type::Combinator.bot : singleton
         end
 
-        # Top/Dynamic narrow to `Nominal[class_name]` so dispatch
-        # can resolve through the asked class; Bot stays Bot.
+        # Top/Dynamic narrow to `Nominal[class_name]` so dispatch can resolve through the asked
+        # class; Bot stays Bot.
         def narrow_class_other(type, class_name)
           case type
           when Type::Dynamic, Type::Top then Type::Combinator.nominal_of(class_name)
@@ -2520,11 +2310,10 @@ module Rigor
           end
         end
 
-        # Returns `true` when an instance of `rigor_class_name`
-        # satisfies `is_a?(target_class_name)` (or
-        # `instance_of?(target_class_name)` when `exact: true`).
-        # Falls back to the safe `false` when either name does not
-        # resolve through the analyzer environment.
+        # Returns `true` when an instance of `rigor_class_name` satisfies
+        # `is_a?(target_class_name)` (or `instance_of?(target_class_name)` when `exact: true`).
+        # Falls back to the safe `false` when either name does not resolve through the analyzer
+        # environment.
         def subclass_of?(rigor_class_name, target_class_name, context)
           return rigor_class_name == target_class_name if context.exact
 
@@ -2533,11 +2322,9 @@ module Rigor
           )
         end
 
-        # Compares two class names through the analyzer environment.
-        # Returns `:equal` when they resolve to the same class,
-        # `:subclass` when `lhs <= rhs`, `:superclass` when
-        # `rhs <= lhs`, `:disjoint` when neither, and `:unknown` when
-        # either name does not resolve.
+        # Compares two class names through the analyzer environment. Returns `:equal` when they
+        # resolve to the same class, `:subclass` when `lhs <= rhs`, `:superclass` when `rhs <=
+        # lhs`, `:disjoint` when neither, and `:unknown` when either name does not resolve.
         def class_ordering(lhs, rhs, context)
           return :equal if lhs == rhs
 
@@ -2565,11 +2352,10 @@ module Rigor
           end
         end
 
-        # Narrows a safe-navigation call's receiver (`v&.foo`) to its
-        # non-nil fragment on the truthy edge, returning `[truthy, falsey]`
-        # or nil when nothing applies (not safe-nav, opaque receiver, or
-        # already non-nil). Used standalone for a bare `v&.foo` truthy
-        # edge and as a post-pass over the existing predicate edges.
+        # Narrows a safe-navigation call's receiver (`v&.foo`) to its non-nil fragment on the
+        # truthy edge, returning `[truthy, falsey]` or nil when nothing applies (not safe-nav,
+        # opaque receiver, or already non-nil). Used standalone for a bare `v&.foo` truthy edge
+        # and as a post-pass over the existing predicate edges.
         def analyse_safe_nav_receiver(node, scope)
           return nil unless node.safe_navigation?
 
@@ -2590,12 +2376,11 @@ module Rigor
           [scope.public_send(writer, receiver.name, non_nil), scope]
         end
 
-        # Layers the safe-nav non-nil truthy narrowing over the edges an
-        # existing predicate path already produced, so a safe-nav string
-        # predicate (`v&.start_with?(x)`) keeps its relational fact AND
-        # proves `v` non-nil on the truthy edge. Re-runs the predicate's
-        # narrowing under the non-nil truthy scope so the fact is attached
-        # to the narrowed binding. No-op for non-safe-nav calls.
+        # Layers the safe-nav non-nil truthy narrowing over the edges an existing predicate path
+        # already produced, so a safe-nav string predicate (`v&.start_with?(x)`) keeps its
+        # relational fact AND proves `v` non-nil on the truthy edge. Re-runs the predicate's
+        # narrowing under the non-nil truthy scope so the fact is attached to the narrowed
+        # binding. No-op for non-safe-nav calls.
         def apply_safe_nav_non_nil(node, scope, edges)
           return edges unless node.safe_navigation? && edges
 
@@ -2610,23 +2395,20 @@ module Rigor
           [truthy.public_send(writer, receiver.name, non_nil), falsey]
         end
 
-        # `a && b` short-circuits: the truthy edge is the truthy edge
-        # of `b` evaluated under `a`'s truthy scope; the falsey edge
-        # is the union of `a`'s falsey scope (b skipped) and `b`'s
-        # falsey scope (b ran but returned falsey). When a sub-edge
-        # cannot be narrowed we fall back to the entry scope so the
-        # caller still sees consistent keys across the two output
-        # scopes.
+        # `a && b` short-circuits: the truthy edge is the truthy edge of `b` evaluated under
+        # `a`'s truthy scope; the falsey edge is the union of `a`'s falsey scope (b skipped) and
+        # `b`'s falsey scope (b ran but returned falsey). When a sub-edge cannot be narrowed we
+        # fall back to the entry scope so the caller still sees consistent keys across the two
+        # output scopes.
         def analyse_and(node, scope)
           truthy_a, falsey_a = analyse(node.left, scope) || [scope, scope]
           truthy_b, falsey_b = analyse(node.right, truthy_a) || [truthy_a, truthy_a]
           [truthy_b, falsey_a.join(falsey_b)]
         end
 
-        # `a || b` short-circuits: the truthy edge is the union of
-        # `a`'s truthy scope (b skipped) and `b`'s truthy scope (b
-        # ran and was truthy); the falsey edge is `b`'s falsey scope
-        # evaluated under `a`'s falsey scope.
+        # `a || b` short-circuits: the truthy edge is the union of `a`'s truthy scope (b
+        # skipped) and `b`'s truthy scope (b ran and was truthy); the falsey edge is `b`'s
+        # falsey scope evaluated under `a`'s falsey scope.
         def analyse_or(node, scope)
           truthy_a, falsey_a = analyse(node.left, scope) || [scope, scope]
           truthy_b, falsey_b = analyse(node.right, falsey_a) || [falsey_a, falsey_a]