rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/hkt_reducer.rb

@@ -5,40 +5,29 @@ require_relative "budget_trace"
 
 module Rigor
   module Inference
-    # ADR-20 Slice 2a — reducer that walks a `Definition`'s
-    # `body_tree` against a concrete `Type::App` and returns a
-    # fully-typed `Rigor::Type`.
+    # ADR-20 Slice 2a — reducer that walks a `Definition`'s `body_tree` against a concrete
+    # `Type::App` and returns a fully-typed `Rigor::Type`.
     #
-    # Reduction is the operational interpretation of ADR-20
-    # § D4 ("Evaluation rules"):
+    # Reduction is the operational interpretation of ADR-20 § D4 ("Evaluation rules"):
     #
-    # 1. **Resolve `F`.** Look up the registered body via
-    #    `registry.definition(uri)`.
-    # 2. **Substitute arguments.** Walk the body tree, replacing
-    #    `{HktBody::Param}` nodes with the matching positional
-    #    arg from the application.
-    # 3. **Build types.** `{HktBody::TypeLeaf}` returns its
-    #    wrapped type as-is; `{HktBody::Union}` and
-    #    `{HktBody::NominalApp}` route their reduced children
-    #    through `Type::Combinator.union` / `.nominal_of` so
-    #    normalization applies.
-    # 4. **Recurse on `{HktBody::AppRef}` nodes.** Reduce the
-    #    args first; if the resulting `(uri, args)` matches an
-    #    App already on the current reduction stack, return the
-    #    in-progress `Type::App` carrier as-is (lazy
-    #    self-reference handling — the standard "tying the
-    #    knot" trick for recursive type aliases like
-    #    `json::value`). Otherwise build a fresh
-    #    `Type::App` and recursively reduce it against the
-    #    same registry, sharing the fuel budget.
-    # 5. **Fuel budget.** Each visited node consumes one unit.
-    #    On exhaustion, reduction unwinds to `app.bound`.
+    # 1. **Resolve `F`.** Look up the registered body via `registry.definition(uri)`.
+    # 2. **Substitute arguments.** Walk the body tree, replacing `{HktBody::Param}` nodes with
+    #    the matching positional arg from the application.
+    # 3. **Build types.** `{HktBody::TypeLeaf}` returns its wrapped type as-is; `{HktBody::Union}`
+    #    and `{HktBody::NominalApp}` route their reduced children through
+    #    `Type::Combinator.union` / `.nominal_of` so normalization applies.
+    # 4. **Recurse on `{HktBody::AppRef}` nodes.** Reduce the args first; if the resulting
+    #    `(uri, args)` matches an App already on the current reduction stack, return the
+    #    in-progress `Type::App` carrier as-is (lazy self-reference handling — the standard
+    #    "tying the knot" trick for recursive type aliases like `json::value`). Otherwise build a
+    #    fresh `Type::App` and recursively reduce it against the same registry, sharing the fuel
+    #    budget.
+    # 5. **Fuel budget.** Each visited node consumes one unit. On exhaustion, reduction unwinds to
+    #    `app.bound`.
     #
-    # The reducer is **pure** with respect to its inputs (the
-    # registry + the App) but uses a per-call mutable state
-    # bag for fuel + cycle tracking. Concurrent reductions
-    # MUST allocate fresh reducers (or fresh `_reduce` calls)
-    # — the per-call state is not shared.
+    # The reducer is **pure** with respect to its inputs (the registry + the App) but uses a
+    # per-call mutable state bag for fuel + cycle tracking. Concurrent reductions MUST allocate
+    # fresh reducers (or fresh `_reduce` calls) — the per-call state is not shared.
     class HktReducer
       DEFAULT_FUEL = 64
 
@@ -53,12 +42,10 @@ module Rigor
       # Reduce `app` against the registry.
       #
       # @param app [Rigor::Type::App]
-      # @param fuel [Integer] reduction-step budget (default 64
-      #   per ADR-20 WD3). Each visited body node costs one
-      #   unit. On exhaustion the reduction returns `app.bound`.
-      # @return [Rigor::Type] the reduced type, or `app.bound`
-      #   when reduction is impossible (URI not defined, arity
-      #   mismatch, body_tree absent, fuel exhausted).
+      # @param fuel [Integer] reduction-step budget (default 64 per ADR-20 WD3). Each visited
+      #   body node costs one unit. On exhaustion the reduction returns `app.bound`.
+      # @return [Rigor::Type] the reduced type, or `app.bound` when reduction is impossible (URI
+      #   not defined, arity mismatch, body_tree absent, fuel exhausted).
       def reduce(app, fuel: DEFAULT_FUEL)
         raise ArgumentError, "expected a Rigor::Type::App, got #{app.class}" unless app.is_a?(Type::App)
 
@@ -109,13 +96,12 @@ module Rigor
         end
       end
 
-      # ADR-20 § D3 conditional reduction. Resolves the test
-      # against the current bindings and picks a branch:
+      # ADR-20 § D3 conditional reduction. Resolves the test against the current bindings and
+      # picks a branch:
       #
       # - test = `yes` → return the reduced `then_branch`.
       # - test = `no`  → return the reduced `else_branch`.
-      # - test = `maybe` → widen to the union of both
-      #   reduced branches (per ADR-20 WD7).
+      # - test = `maybe` → widen to the union of both reduced branches (per ADR-20 WD7).
       def walk_conditional(node, bindings:, state:)
         verdict = evaluate_test(node.test, bindings: bindings, state: state)
         case verdict
@@ -150,25 +136,21 @@ module Rigor
         end
       end
 
-      # `left <: right`. Slice 7a verdict policy: structural
-      # equality is `:yes`; clearly-disjoint nominal /
-      # constant pairs are `:no`; everything else is `:maybe`
-      # (widens to the union per ADR-20 WD7 — robustness
-      # principle keeps us conservative on undecided tests).
+      # `left <: right`. Slice 7a verdict policy: structural equality is `:yes`; clearly-disjoint
+      # nominal / constant pairs are `:no`; everything else is `:maybe` (widens to the union per
+      # ADR-20 WD7 — robustness principle keeps us conservative on undecided tests).
       def subtype_verdict(left, right)
         return :yes if left == right
 
-        # Both Nominals with different class names AND
-        # neither carries Dynamic — `:no` (statically
-        # disjoint). For any other shape pair, `:maybe`.
+        # Both Nominals with different class names AND neither carries Dynamic — `:no`
+        # (statically disjoint). For any other shape pair, `:maybe`.
         return :no if disjoint_nominals?(left, right)
         return :no if disjoint_constants?(left, right)
 
         :maybe
       end
 
-      # Structural equality verdict — same shape as
-      # subtype_verdict but symmetric.
+      # Structural equality verdict — same shape as subtype_verdict but symmetric.
       def equality_verdict(left, right)
         return :yes if left == right
         return :no if disjoint_nominals?(left, right)
@@ -198,11 +180,9 @@ module Rigor
       end
 
       def reduce_app_ref(uri, reduced_args, state:)
-        # Cycle detection — when the same `(uri, args)` is
-        # already on the reduction stack, return the
-        # in-progress App carrier as-is so recursive type
-        # aliases (`Array[App[json::value, K]]` inside the
-        # `json::value` body) terminate.
+        # Cycle detection — when the same `(uri, args)` is already on the reduction stack, return
+        # the in-progress App carrier as-is so recursive type aliases (`Array[App[json::value,
+        # K]]` inside the `json::value` body) terminate.
         existing = state.in_progress_for(uri, reduced_args)
         return existing if existing
 
@@ -219,9 +199,8 @@ module Rigor
         end
       end
 
-      # Per-call mutable bag carrying the remaining fuel
-      # budget and the active reduction stack (for cycle
-      # detection). Not shared across `reduce` calls.
+      # Per-call mutable bag carrying the remaining fuel budget and the active reduction stack
+      # (for cycle detection). Not shared across `reduce` calls.
       class State
         def initialize(fuel:)
           @fuel = fuel

data/lib/rigor/inference/hkt_registry.rb

@@ -4,41 +4,32 @@ require_relative "hkt_body"
 
 module Rigor
   module Inference
-    # ADR-20 § "Decision D1 / D2" — registry of Lightweight HKT
-    # tag registrations + type-function bodies parsed off the
-    # `%a{rigor:v1:hkt_register: ...}` /
-    # `%a{rigor:v1:hkt_define: ...}` annotations in shipped
-    # `.rbs` files.
+    # ADR-20 § "Decision D1 / D2" — registry of Lightweight HKT tag registrations + type-function
+    # bodies parsed off the `%a{rigor:v1:hkt_register: ...}` / `%a{rigor:v1:hkt_define: ...}`
+    # annotations in shipped `.rbs` files.
     #
-    # The registry stores registration metadata (arity, variance,
-    # bound) and the definition body as both a raw String and an
-    # evaluable `HktBody` node tree. `HktReducer` (Slice 2a) and
-    # `HktBodyParser` (Slice 2b) are both shipped and reduce
-    # `Type::App` instances against the definition. The carrier
-    # never needs to read from the registry
-    # because Slice 1's `Type::App` carries its `bound` directly;
-    # the registry exists at this slice solely so the parser
+    # The registry stores registration metadata (arity, variance, bound) and the definition body
+    # as both a raw String and an evaluable `HktBody` node tree. `HktReducer` (Slice 2a) and
+    # `HktBodyParser` (Slice 2b) are both shipped and reduce `Type::App` instances against the
+    # definition. The carrier never needs to read from the registry because Slice 1's `Type::App`
+    # carries its `bound` directly; the registry exists at this slice solely so the parser
     # round-trip and downstream slices have a stable target API.
     #
-    # The registry is immutable after construction. Callers that
-    # need to extend it (e.g. plugin registrations layered on top
-    # of stdlib registrations) MUST build a new registry via
-    # `merge` rather than mutating an existing one. This keeps the
-    # registry shareable across Ractor boundaries per ADR-15.
+    # The registry is immutable after construction. Callers that need to extend it (e.g. plugin
+    # registrations layered on top of stdlib registrations) MUST build a new registry via `merge`
+    # rather than mutating an existing one. This keeps the registry shareable across Ractor
+    # boundaries per ADR-15.
     class HktRegistry
       # Frozen value object recording one tag registration.
       #
-      # - `uri`: namespaced Symbol per ADR-20 WD1 (must include
-      #   `"::"`).
-      # - `arity`: positive Integer — the number of formal
-      #   parameters the registered constructor takes.
-      # - `variance`: ordered Array of Symbols, one per
-      #   parameter, each `:out` (covariant), `:in`
+      # - `uri`: namespaced Symbol per ADR-20 WD1 (must include `"::"`).
+      # - `arity`: positive Integer — the number of formal parameters the registered constructor
+      #   takes.
+      # - `variance`: ordered Array of Symbols, one per parameter, each `:out` (covariant), `:in`
       #   (contravariant), or `:inv` (invariant; default).
-      # - `bound`: a `Rigor::Type` to erase to when an `App`
-      #   referring to this URI cannot be reduced. Defaults to
-      #   `Dynamic[Top]` (the parser fills in the default when
-      #   the annotation omits `bound:`).
+      # - `bound`: a `Rigor::Type` to erase to when an `App` referring to this URI cannot be
+      #   reduced. Defaults to `Dynamic[Top]` (the parser fills in the default when the
+      #   annotation omits `bound:`).
       Registration = Data.define(:uri, :arity, :variance, :bound) do
         def initialize(uri:, arity:, variance:, bound:)
           raise ArgumentError, "uri must be a Symbol, got #{uri.class}" unless uri.is_a?(Symbol)
@@ -61,21 +52,16 @@ module Rigor
         end
       end
 
-      # Frozen value object recording one type-function
-      # definition.
+      # Frozen value object recording one type-function definition.
       #
-      # `body` is the raw String payload from the `%a{...}`
-      # annotation (Slice 1's parser populates it); parsed into
-      # `body_tree` by `HktBodyParser` (Slice 2b, shipped).
+      # `body` is the raw String payload from the `%a{...}` annotation (Slice 1's parser
+      # populates it); parsed into `body_tree` by `HktBodyParser` (Slice 2b, shipped).
       #
-      # `body_tree` is the evaluable form: a
-      # `Rigor::Inference::HktBody::*` node tree the Slice 2a
-      # reducer walks against the application's concrete
-      # arguments. Plugin and Rigor-bundled overlay authors
-      # construct it programmatically through
-      # {.definition_with_body_tree}. The reducer treats a
-      # `nil` `body_tree` as "definition not yet evaluable"
-      # and returns the registered bound.
+      # `body_tree` is the evaluable form: a `Rigor::Inference::HktBody::*` node tree the Slice 2a
+      # reducer walks against the application's concrete arguments. Plugin and Rigor-bundled
+      # overlay authors construct it programmatically through {.definition_with_body_tree}. The
+      # reducer treats a `nil` `body_tree` as "definition not yet evaluable" and returns the
+      # registered bound.
       Definition = Data.define(:uri, :params, :body, :body_tree, :source_path, :source_line) do
         def initialize(uri:, params:, body:, body_tree: nil, source_path: nil, source_line: nil)
           raise ArgumentError, "uri must be a Symbol, got #{uri.class}" unless uri.is_a?(Symbol)
@@ -97,11 +83,9 @@ module Rigor
         end
       end
 
-      # Convenience constructor for callers that have a body
-      # tree but no raw String — typically Rigor-bundled HKT
-      # overlays that build the body programmatically. The
-      # raw `body` slot is filled with an empty placeholder
-      # so existing consumers keep their type contract.
+      # Convenience constructor for callers that have a body tree but no raw String — typically
+      # Rigor-bundled HKT overlays that build the body programmatically. The raw `body` slot is
+      # filled with an empty placeholder so existing consumers keep their type contract.
       def self.definition_with_body_tree(uri:, params:, body_tree:, source_path: nil, source_line: nil)
         Definition.new(
           uri: uri,
@@ -139,10 +123,8 @@ module Rigor
         @definitions[uri]
       end
 
-      # @return [HktRegistry] a new registry whose entries are
-      #   the union of this registry's and `other`'s. On URI
-      #   collisions `other`'s entries win (last-write-wins; OQ3
-      #   tentative).
+      # @return [HktRegistry] a new registry whose entries are the union of this registry's and
+      #   `other`'s. On URI collisions `other`'s entries win (last-write-wins; OQ3 tentative).
       def merge(other)
         raise ArgumentError, "merge target must be an HktRegistry, got #{other.class}" unless other.is_a?(HktRegistry)
 
@@ -156,41 +138,33 @@ module Rigor
         @registrations.empty? && @definitions.empty?
       end
 
-      # ADR-20 Slice 2a — reduce an `App` against this
-      # registry. Convenience wrapper around `HktReducer.new(self).reduce`.
-      # Each call allocates a fresh reducer; concurrent
-      # reductions are safe.
+      # ADR-20 Slice 2a — reduce an `App` against this registry. Convenience wrapper around
+      # `HktReducer.new(self).reduce`. Each call allocates a fresh reducer; concurrent reductions
+      # are safe.
       def reduce(app, fuel: HktReducer::DEFAULT_FUEL)
         HktReducer.new(self).reduce(app, fuel: fuel)
       end
 
-      # ADR-20 slice 2e — scan a Rigor RbsLoader for
-      # `rigor:v1:hkt_register` / `rigor:v1:hkt_define`
-      # annotations attached to class- or module-level
-      # declarations in the loaded RBS env, parse them via
-      # {Rigor::RbsExtended::HktDirectives}, and return a new
-      # registry that is the union of `base` and every parsed
-      # entry. Last-write-wins on URI collisions per
-      # {#merge}'s contract. Fail-soft on per-annotation parse
-      # errors (the reporter records an `:info` entry; the
-      # other annotations still apply).
+      # ADR-20 slice 2e — scan a Rigor RbsLoader for `rigor:v1:hkt_register` /
+      # `rigor:v1:hkt_define` annotations attached to class- or module-level declarations in the
+      # loaded RBS env, parse them via {Rigor::RbsExtended::HktDirectives}, and return a new
+      # registry that is the union of `base` and every parsed entry. Last-write-wins on URI
+      # collisions per {#merge}'s contract. Fail-soft on per-annotation parse errors (the reporter
+      # records an `:info` entry; the other annotations still apply).
       #
       # @param rbs_loader [Rigor::Environment::RbsLoader]
-      # @param base [HktRegistry] starting registry (typically
-      #   the bundled `Rigor::Builtins::HktBuiltins.registry`).
-      # @param name_scope [Rigor::Environment::NameScope, nil]
-      #   threaded through to the bound resolver for class-name
-      #   lookups; safe to omit during scanning since hkt
-      #   bounds are typically `untyped` or stdlib classes.
-      # @param reporter [#record, nil] same fail-soft reporter
-      #   contract the other RBS-extended parsers use.
+      # @param base [HktRegistry] starting registry (typically the bundled
+      #   `Rigor::Builtins::HktBuiltins.registry`).
+      # @param name_scope [Rigor::Environment::NameScope, nil] threaded through to the bound
+      #   resolver for class-name lookups; safe to omit during scanning since hkt bounds are
+      #   typically `untyped` or stdlib classes.
+      # @param reporter [#record, nil] same fail-soft reporter contract the other RBS-extended
+      #   parsers use.
       def self.scan_rbs_loader(rbs_loader, base: EMPTY, name_scope: nil, reporter: nil)
         return base if rbs_loader.nil?
 
-        # Required lazily here to avoid a hard circular
-        # require between hkt_registry / hkt_directives;
-        # HktDirectives requires HktRegistry to construct its
-        # value objects.
+        # Required lazily here to avoid a hard circular require between hkt_registry /
+        # hkt_directives; HktDirectives requires HktRegistry to construct its value objects.
         require_relative "../rbs_extended/hkt_directives"
 
         registrations = []

data/lib/rigor/inference/indexed_narrowing.rb

@@ -7,62 +7,50 @@ require_relative "mutation_widening"
 
 module Rigor
   module Inference
-    # Closes the "`params[:f] ||= []; params[:f] << x`" precision
-    # gap surfaced by the Redmine 6.1.2 `Query#as_params` survey
-    # (ROADMAP § Future cycles / Type-language / engine —
+    # Closes the "`params[:f] ||= []; params[:f] << x`" precision gap surfaced by the Redmine
+    # 6.1.2 `Query#as_params` survey (ROADMAP § Future cycles / Type-language / engine —
     # "Indexed-collection narrowing through `Hash[k] ||= default`").
     #
-    # After `receiver[key] ||= default` the next read at
-    # `receiver[key]` is known non-nil, but Rigor types each
-    # `Hash#[]` independently and the subsequent `<<` / `[]=` /
-    # other mutator dispatches against the un-narrowed result —
-    # which on a `HashShape{}` carrier folds to `Constant[nil]`.
+    # After `receiver[key] ||= default` the next read at `receiver[key]` is known non-nil, but
+    # Rigor types each `Hash#[]` independently and the subsequent `<<` / `[]=` / other mutator
+    # dispatches against the un-narrowed result — which on a `HashShape{}` carrier folds to
+    # `Constant[nil]`.
     #
-    # This module is the address-recogniser + invalidator shared
-    # by {Inference::StatementEvaluator}'s `eval_index_or_write`
-    # handler (which RECORDS the narrowing) and `eval_call`
-    # (which INVALIDATES on intervening writes / mutators) and
-    # by {Inference::ExpressionTyper}'s `call_type_for` (which
-    # CONSUMES the narrowing when typing a follow-up `[]` read).
+    # This module is the address-recogniser + invalidator shared by
+    # {Inference::StatementEvaluator}'s `eval_index_or_write` handler (which RECORDS the
+    # narrowing) and `eval_call` (which INVALIDATES on intervening writes / mutators) and by
+    # {Inference::ExpressionTyper}'s `call_type_for` (which CONSUMES the narrowing when typing a
+    # follow-up `[]` read).
     #
-    # **Stable receivers.** A receiver is "stable" iff it is a
-    # `LocalVariableReadNode` or `InstanceVariableReadNode`.
-    # Method-call chains (`foo.bar[:k]`) and other shapes are
-    # rejected because a follow-up read against an identical-
-    # looking AST chain has no guarantee of resolving to the
-    # same runtime value — narrowing it would invent a fact.
+    # **Stable receivers.** A receiver is "stable" iff it is a `LocalVariableReadNode` or
+    # `InstanceVariableReadNode`. Method-call chains (`foo.bar[:k]`) and other shapes are
+    # rejected because a follow-up read against an identical-looking AST chain has no guarantee
+    # of resolving to the same runtime value — narrowing it would invent a fact.
     #
-    # **Stable keys.** A key is "stable" iff it is a literal
-    # `SymbolNode` / `StringNode` / `IntegerNode`. Local-variable
-    # keys (`params[field]`) are excluded for the same
-    # invent-a-fact reason: the local could be rebound between
-    # the `||=` and the read.
+    # **Stable keys.** A key is "stable" iff it is a literal `SymbolNode` / `StringNode` /
+    # `IntegerNode`. Local-variable keys (`params[field]`) are excluded for the same
+    # invent-a-fact reason: the local could be rebound between the `||=` and the read.
     #
-    # **Invalidation.** Three conditions drop a recorded
-    # narrowing:
-    # - The receiver variable is rebound (handled inside
-    #   `Scope#with_local` / `Scope#with_ivar`).
-    # - An intervening `receiver[key] = value` writes the same
-    #   slot — `:[]=` could rebind the slot to nil; conservative
-    #   drop.
-    # - An intervening mutator from {MutationWidening::HASH_MUTATORS}
-    #   or {MutationWidening::ARRAY_MUTATORS} runs against the
-    #   receiver (e.g. `params.delete(:f)`, `params.clear`).
+    # **Invalidation.** Three conditions drop a recorded narrowing:
+    # - The receiver variable is rebound (handled inside `Scope#with_local` / `Scope#with_ivar`).
+    # - An intervening `receiver[key] = value` writes the same slot — `:[]=` could rebind the
+    #   slot to nil; conservative drop.
+    # - An intervening mutator from {MutationWidening::HASH_MUTATORS} or
+    #   {MutationWidening::ARRAY_MUTATORS} runs against the receiver (e.g. `params.delete(:f)`,
+    #   `params.clear`).
     #
-    # All three are implemented in `StatementEvaluator#eval_call`'s
-    # post-dispatch path through {.invalidate_after_call}.
+    # All three are implemented in `StatementEvaluator#eval_call`'s post-dispatch path through
+    # {.invalidate_after_call}.
     module IndexedNarrowing
-      # Literal Prism nodes whose Ruby value the analyzer trusts
-      # as a stable address. Symbol / String are the dominant
-      # Hash key shapes; Integer covers numerically-keyed Hashes
-      # and Array indices.
+      # Literal Prism nodes whose Ruby value the analyzer trusts as a stable address. Symbol /
+      # String are the dominant Hash key shapes; Integer covers numerically-keyed Hashes and
+      # Array indices.
       STABLE_KEY_NODES = [Prism::SymbolNode, Prism::StringNode, Prism::IntegerNode].freeze
 
       module_function
 
-      # Returns `[receiver_kind, receiver_name]` when `node` is a
-      # `LocalVariableReadNode` or `InstanceVariableReadNode`,
-      # otherwise nil.
+      # Returns `[receiver_kind, receiver_name]` when `node` is a `LocalVariableReadNode` or
+      # `InstanceVariableReadNode`, otherwise nil.
       def stable_receiver(node)
         case node
         when Prism::LocalVariableReadNode then [:local, node.name]
@@ -70,9 +58,8 @@ module Rigor
         end
       end
 
-      # Returns the literal Ruby value when `node` is a stable
-      # key shape, otherwise nil. Symbols → `Symbol`,
-      # Strings → `String` (unescaped), Integers → `Integer`.
+      # Returns the literal Ruby value when `node` is a stable key shape, otherwise nil.
+      # Symbols → `Symbol`, Strings → `String` (unescaped), Integers → `Integer`.
       def stable_key(node)
         case node
         when Prism::SymbolNode then node.unescaped.to_sym
@@ -81,14 +68,11 @@ module Rigor
         end
       end
 
-      # Returns `[receiver_kind, receiver_name, key]` when the
-      # CallNode is a `receiver[key]` read or write whose
-      # receiver and key are both stable, otherwise nil. Used
-      # by both the recorder (for `IndexOrWriteNode`'s
-      # receiver/arguments triplet) and the invalidator (for
-      # `CallNode :[]=` / mutator calls). Treats only the FIRST
-      # argument as the key; `:[]=`'s second argument is the
-      # rvalue and is not part of the address.
+      # Returns `[receiver_kind, receiver_name, key]` when the CallNode is a `receiver[key]` read
+      # or write whose receiver and key are both stable, otherwise nil. Used by both the recorder
+      # (for `IndexOrWriteNode`'s receiver/arguments triplet) and the invalidator (for `CallNode
+      # :[]=` / mutator calls). Treats only the FIRST argument as the key; `:[]=`'s second
+      # argument is the rvalue and is not part of the address.
       def stable_address(receiver_node, key_node)
         receiver = stable_receiver(receiver_node)
         return nil if receiver.nil?
@@ -99,10 +83,9 @@ module Rigor
         [receiver.first, receiver.last, key]
       end
 
-      # Looks up a recorded narrowing for `receiver[key]` against
-      # `scope`, returning the narrowed type or nil when no
-      # entry applies. Used by ExpressionTyper's `[]` dispatch
-      # to refine the result of a stable indexed read.
+      # Looks up a recorded narrowing for `receiver[key]` against `scope`, returning the narrowed
+      # type or nil when no entry applies. Used by ExpressionTyper's `[]` dispatch to refine the
+      # result of a stable indexed read.
       def lookup_for_call(node, scope)
         return nil unless node.is_a?(Prism::CallNode)
         return nil unless node.name == :[]
@@ -115,18 +98,14 @@ module Rigor
         scope.indexed_narrowing(*address)
       end
 
-      # Removes recorded narrowings invalidated by `call_node`.
-      # Two patterns:
+      # Removes recorded narrowings invalidated by `call_node`. Two patterns:
       #
-      # - `receiver[key] = value` (a `:[]=` against a stable
-      #   address): drop the specific `(receiver, key)` entry.
-      # - Any mutator from `HASH_MUTATORS` / `ARRAY_MUTATORS`
-      #   against a stable receiver: drop EVERY entry rooted
-      #   at that receiver, because the mutator could rebind
-      #   any slot.
+      # - `receiver[key] = value` (a `:[]=` against a stable address): drop the specific
+      #   `(receiver, key)` entry.
+      # - Any mutator from `HASH_MUTATORS` / `ARRAY_MUTATORS` against a stable receiver: drop
+      #   EVERY entry rooted at that receiver, because the mutator could rebind any slot.
       #
-      # Returns the updated scope. Always-safe (only forgets;
-      # never invents).
+      # Returns the updated scope. Always-safe (only forgets; never invents).
       def invalidate_after_call(call_node:, current_scope:)
         return current_scope unless call_node.is_a?(Prism::CallNode)
 
@@ -161,18 +140,13 @@ module Rigor
         current_scope.without_indexed_narrowings_for(*receiver)
       end
 
-      # Companion invalidator for single-hop method-chain
-      # narrowings (ROADMAP § Future cycles — "Method-call
-      # receiver narrowing across stable receivers", B2 from
-      # the slice's design notes). Drops every
-      # `(receiver, *)` chain narrowing rooted at the call's
-      # OUTER stable receiver — matching the ROADMAP's "any
-      # intervening method call against the same receiver"
-      # criterion. A call against `x.last` (the OUTER receiver
-      # is a `CallNode`, not a stable root) does NOT drop
-      # narrowings keyed on `x`, so the worked-site
-      # `x.last << y` pattern correctly preserves the chain
-      # narrowing for any further `x.last` read in the same
+      # Companion invalidator for single-hop method-chain narrowings (ROADMAP § Future cycles —
+      # "Method-call receiver narrowing across stable receivers", B2 from the slice's design
+      # notes). Drops every `(receiver, *)` chain narrowing rooted at the call's OUTER stable
+      # receiver — matching the ROADMAP's "any intervening method call against the same
+      # receiver" criterion. A call against `x.last` (the OUTER receiver is a `CallNode`, not a
+      # stable root) does NOT drop narrowings keyed on `x`, so the worked-site `x.last << y`
+      # pattern correctly preserves the chain narrowing for any further `x.last` read in the same
       # body. Always-safe (only forgets; never invents).
       def invalidate_chain_after_call(call_node:, current_scope:)
         return current_scope unless call_node.is_a?(Prism::CallNode)

data/lib/rigor/inference/macro_block_self_type.rb

@@ -4,35 +4,27 @@ require_relative "../type"
 
 module Rigor
   module Inference
-    # ADR-16 Tier A — engine hook. Consults every registered
-    # plugin manifest's `block_as_methods` entries to decide
-    # whether a block call site qualifies for `Scope#self_type`
-    # narrowing.
+    # ADR-16 Tier A — engine hook. Consults every registered plugin manifest's `block_as_methods`
+    # entries to decide whether a block call site qualifies for `Scope#self_type` narrowing.
     #
     # The match contract for a class-level DSL like Sinatra's
     # `class MyApp < Sinatra::Base; get '/foo' do ... end; end`:
     #
-    # - the call's lexical receiver type is `Singleton[X]`
-    #   (the implicit-self in a class body, or an explicit
-    #   `MyApp.get(...)` call);
-    # - the underlying class `X` equals or inherits from the
-    #   entry's `receiver_constraint`;
+    # - the call's lexical receiver type is `Singleton[X]` (the implicit-self in a class body, or
+    #   an explicit `MyApp.get(...)` call);
+    # - the underlying class `X` equals or inherits from the entry's `receiver_constraint`;
     # - the call's method name is in the entry's `method_names`.
     #
-    # On a match the helper returns the **instance** type of
-    # the receiver class (`Nominal[X]`) — the narrowed
-    # `self_type` for the block body, matching Sinatra's
-    # runtime semantics where `Sinatra::Base#generate_method`
-    # turns the block into an instance method of the user's
-    # app class.
+    # On a match the helper returns the **instance** type of the receiver class (`Nominal[X]`) —
+    # the narrowed `self_type` for the block body, matching Sinatra's runtime semantics where
+    # `Sinatra::Base#generate_method` turns the block into an instance method of the user's app
+    # class.
     #
-    # Slice 1b ships the floor only (per ADR-16 § WD13):
-    # bare-identifier method lookups inside the block resolve
-    # through the inference engine's normal `self_type`-driven
-    # path, so methods declared on `Sinatra::Base` (RBS or
-    # otherwise) become visible. Precision additions —
-    # parameter-typed block params, declared per-verb argument
-    # contracts — are ceiling concerns for later slices.
+    # Slice 1b ships the floor only (per ADR-16 § WD13): bare-identifier method lookups inside the
+    # block resolve through the inference engine's normal `self_type`-driven path, so methods
+    # declared on `Sinatra::Base` (RBS or otherwise) become visible. Precision additions —
+    # parameter-typed block params, declared per-verb argument contracts — are ceiling concerns
+    # for later slices.
     module MacroBlockSelfType
       module_function
 
@@ -51,12 +43,9 @@ module Rigor
         receiver_class_name = singleton_receiver_class_name(receiver_type)
         return nil if receiver_class_name.nil?
 
-        # ADR-52 WD1 — the verb-keyed table compiled at registry build
-        # replaces the per-call plugins × block_as_methods linear scan.
-        # Entries arrive in (plugin registration, declaration) order, so
-        # the first ancestry match below is the same entry the previous
-        # walk returned; the method-name membership the old `matches?` checked
-        # is guaranteed by the table key.
+        # ADR-52 WD1 — the verb-keyed table compiled at registry build. Entries arrive in
+        # (plugin registration, declaration) order; the method-name membership is guaranteed
+        # by the table key.
         entries = registry.contribution_index.block_entries_for(call_node.name)
         entries.each do |entry|
           if receiver_class_inherits_from?(receiver_class_name, entry.receiver_constraint, environment)
@@ -66,12 +55,10 @@ module Rigor
         nil
       end
 
-      # Tier A's match contract is intentionally narrow:
-      # class-level DSL calls (receiver is `Singleton[X]`) only.
-      # Instance-receiver calls and DSL forms whose block body
-      # binds a different `self` (Concern's `included do`,
-      # `instance_eval { ... }`) are handled by later slices
-      # (Concern walker, Tier D, etc.) — not Tier A.
+      # Tier A's match contract is intentionally narrow: class-level DSL calls (receiver is
+      # `Singleton[X]`) only. Instance-receiver calls and DSL forms whose block body binds a
+      # different `self` (Concern's `included do`, `instance_eval { ... }`) are handled by later
+      # slices (Concern walker, Tier D, etc.) — not Tier A.
       def singleton_receiver_class_name(receiver_type)
         return nil unless receiver_type.is_a?(Type::Singleton)