rigortype 0.2.7 → 0.2.8

data/plugins/rigor-sinatra/lib/rigor/plugin/sinatra.rb

@@ -4,8 +4,7 @@ require "rigor/plugin"
 
 module Rigor
   module Plugin
-    # ADR-16 Tier A worked plugin: recognises Sinatra's class-
-    # level route DSL.
+    # ADR-16 Tier A worked plugin: recognises Sinatra's class-level route DSL.
     #
     # Sinatra's modular style:
     #
@@ -20,52 +19,35 @@ module Rigor
     #       end
     #     end
     #
-    # At runtime `Sinatra::Base#generate_method`
-    # (`lib/sinatra/base.rb:1788-1793`) does `define_method(name,
-    # &block); remove_method`, turning each block into a real
-    # instance method of the user's app class. The substrate's
-    # Tier A hook (`Rigor::Inference::MacroBlockSelfType`)
-    # replays the same contract statically: the block runs with
-    # `self : Nominal[MyApp]`, so bare identifiers (`params`,
-    # `redirect`, `halt`, `session`, `headers`, `content_type`,
-    # `body`, `status`, `erb`, …) resolve through
-    # `Sinatra::Base`'s RBS via rigor's normal inference path.
+    # At runtime `Sinatra::Base#generate_method` (`lib/sinatra/base.rb:1788-1793`) does
+    # `define_method(name, &block); remove_method`, turning each block into a real instance method of the
+    # user's app class. The substrate's Tier A hook (`Rigor::Inference::MacroBlockSelfType`) replays the
+    # same contract statically: the block runs with `self : Nominal[MyApp]`, so bare identifiers
+    # (`params`, `redirect`, `halt`, `session`, `headers`, `content_type`, `body`, `status`, `erb`, …)
+    # resolve through `Sinatra::Base`'s RBS via rigor's normal inference path.
     #
     # ## Reach
     #
-    # All nine class-level HTTP verb methods Sinatra exposes:
-    # `get`, `post`, `put`, `delete`, `head`, `options`, `patch`,
-    # `link`, `unlink` (`lib/sinatra/base.rb:1531-1553`). Both
-    # modular-style subclasses of `Sinatra::Base` and `Sinatra::Application`
-    # (classic top-level style, when used via `class App <
-    # Sinatra::Application`) match because the receiver
-    # constraint accepts every subclass.
+    # All nine class-level HTTP verb methods Sinatra exposes: `get`, `post`, `put`, `delete`, `head`,
+    # `options`, `patch`, `link`, `unlink` (`lib/sinatra/base.rb:1531-1553`). Both modular-style subclasses
+    # of `Sinatra::Base` and `Sinatra::Application` (classic top-level style, when used via `class App <
+    # Sinatra::Application`) match because the receiver constraint accepts every subclass.
     #
     # ## What the plugin does NOT do (yet)
     #
-    # - **Routing diagnostics.** Path uniqueness, conflict
-    #   detection, named-route reverse lookup — none of these
-    #   are in slice 1c's scope.
-    # - **Custom helpers.** `helpers do ... end` blocks that
-    #   inject module methods into the app's instance namespace
-    #   are Tier C / Tier B work, not Tier A.
-    # - **Configure / settings.** `configure do ... end` and
-    #   `set :session_secret, "..."` are settings DSL, not
-    #   route DSL — handled by separate substrate entries when
-    #   demand surfaces.
-    # - **Classic-style top-level routes.** A bare
-    #   `get '/path' do ... end` at the top of a script (no
-    #   enclosing `class < Sinatra::Base`) is the classic-mode
-    #   pattern (`lib/sinatra/main.rb`). Tier A as currently
-    #   wired requires the receiver's class to be visible at
-    #   the call site; a top-level call's receiver is the
-    #   classic-mode `Sinatra::Application`, which the
-    #   `Sinatra::Delegator` mixin forwards from `main`. The
-    #   classic style is deferred until the demand justifies
-    #   the extra match shape.
+    # - **Routing diagnostics.** Path uniqueness, conflict detection, named-route reverse lookup — none of
+    #   these are in slice 1c's scope.
+    # - **Custom helpers.** `helpers do ... end` blocks that inject module methods into the app's instance
+    #   namespace are Tier C / Tier B work, not Tier A.
+    # - **Configure / settings.** `configure do ... end` and `set :session_secret, "..."` are settings
+    #   DSL, not route DSL — handled by separate substrate entries when demand surfaces.
+    # - **Classic-style top-level routes.** A bare `get '/path' do ... end` at the top of a script (no
+    #   enclosing `class < Sinatra::Base`) is the classic-mode pattern (`lib/sinatra/main.rb`). Tier A as
+    #   currently wired requires the receiver's class to be visible at the call site; a top-level call's
+    #   receiver is the classic-mode `Sinatra::Application`, which the `Sinatra::Delegator` mixin forwards
+    #   from `main`. The classic style is deferred until the demand justifies the extra match shape.
     #
-    # See `plugins/rigor-sinatra/README.md` for usage and the
-    # demo script under `plugins/rigor-sinatra/demo/`.
+    # See `plugins/rigor-sinatra/README.md` for usage and the demo script under `plugins/rigor-sinatra/demo/`.
     class Sinatra < Rigor::Plugin::Base
       manifest(
         id: "sinatra",

data/plugins/rigor-sinatra/lib/rigor-sinatra.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Gem entry point. Required by Rigor's plugin loader when
-# `.rigor.yml` lists `rigor-sinatra` under `plugins:`. The
-# loader expects this `require` to side-effect a call to
-# `Rigor::Plugin.register`, which the body of
-# `lib/rigor/plugin/sinatra.rb` performs at load time.
+# Gem entry point. Required by Rigor's plugin loader when `.rigor.yml` lists `rigor-sinatra` under
+# `plugins:`. The loader expects this `require` to side-effect a call to `Rigor::Plugin.register`, which
+# the body of `lib/rigor/plugin/sinatra.rb` performs at load time.
 require_relative "rigor/plugin/sinatra"

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/absurd_recognizer.rb

@@ -7,11 +7,9 @@ require_relative "type_translator"
 module Rigor
   module Plugin
     class Sorbet < Rigor::Plugin::Base
-      # Slice 6 of ADR-11 — recognises `T.absurd(x)` calls and
-      # composes them with the engine's flow-sensitive
-      # narrowing. `T.absurd` asserts that a code branch is
-      # statically unreachable; it's the standard Sorbet idiom
-      # for case/when exhaustiveness:
+      # Slice 6 of ADR-11 — recognises `T.absurd(x)` calls and composes them with the engine's
+      # flow-sensitive narrowing. `T.absurd` asserts that a code branch is statically unreachable; it's
+      # the standard Sorbet idiom for case/when exhaustiveness:
       #
       #   case x
       #   when A then ...
@@ -20,33 +18,23 @@ module Rigor
       #     T.absurd(x)
       #   end
       #
-      # If every case has been handled, `x` at the `else` branch
-      # has been narrowed to `T.noreturn` (Rigor's `Type::Bot`)
-      # and the assertion holds. If the user forgot a case, `x`
-      # narrows to whatever's left and the assertion is wrong —
-      # we surface that mistake as `plugin.sorbet.absurd-reachable`.
+      # If every case has been handled, `x` at the `else` branch has been narrowed to `T.noreturn`
+      # (Rigor's `Type::Bot`) and the assertion holds. If the user forgot a case, `x` narrows to whatever's
+      # left and the assertion is wrong — we surface that mistake as `plugin.sorbet.absurd-reachable`.
       #
       # ## Two-phase mechanism
       #
-      # The recogniser is invoked from the plugin's `dynamic_return` rule
-      # where the per-node `scope:` carries the proper narrowing
-      # context. The rule:
+      # The recogniser is invoked from the plugin's `dynamic_return` rule where the per-node `scope:`
+      # carries the proper narrowing context. The rule:
       #
-      # - Contributes a `bot` return type regardless of
-      #   reachability (faithful to `T.absurd`'s runtime
-      #   behaviour: it always raises). This lets the engine's
-      #   existing flow analysis treat code after `T.absurd` as
-      #   unreachable, matching what users of Sorbet expect.
-      # - When the branch is REACHABLE (the discriminant's type
-      #   isn't `bot`), the recogniser also records the call
-      #   node in a per-plugin set. The plugin's
-      #   `diagnostics_for_file` later walks the AST for
-      #   `T.absurd` calls and emits a
-      #   `plugin.sorbet.absurd-reachable` warning at every
-      #   call_node whose object identity matches the recorded
-      #   set. We rely on the runner only parsing each file
-      #   once per run, so the same Prism node object is seen
-      #   in both the `dynamic_return` rule and
+      # - Contributes a `bot` return type regardless of reachability (faithful to `T.absurd`'s runtime
+      #   behaviour: it always raises). This lets the engine's existing flow analysis treat code after
+      #   `T.absurd` as unreachable, matching what users of Sorbet expect.
+      # - When the branch is REACHABLE (the discriminant's type isn't `bot`), the recogniser also records
+      #   the call node in a per-plugin set. The plugin's `diagnostics_for_file` later walks the AST for
+      #   `T.absurd` calls and emits a `plugin.sorbet.absurd-reachable` warning at every call_node whose
+      #   object identity matches the recorded set. We rely on the runner only parsing each file once per
+      #   run, so the same Prism node object is seen in both the `dynamic_return` rule and
       #   `diagnostics_for_file`.
       module AbsurdRecognizer
         # @param call_node [Prism::CallNode]
@@ -56,19 +44,17 @@ module Rigor
           return false unless call_node.name == :absurd
           return false unless TypeTranslator.sorbet_t_namespaced?(call_node.receiver)
 
-          # Slice 6 only handles single-argument `T.absurd(x)`;
-          # no-arg / multi-arg shapes are syntax errors at
-          # Sorbet's level too.
+          # Slice 6 only handles single-argument `T.absurd(x)`; no-arg / multi-arg shapes are syntax
+          # errors at Sorbet's level too.
           arguments = call_node.arguments&.arguments
           arguments&.size == 1
         end
 
         # @param call_node [Prism::CallNode]
         # @param scope [Rigor::Scope, nil]
-        # @return [Boolean] true when the discriminant has been
-        #   narrowed to `bot` (the branch is unreachable, so
-        #   `T.absurd` is correct). The caller suppresses the
-        #   `absurd-reachable` diagnostic in this case.
+        # @return [Boolean] true when the discriminant has been narrowed to `bot` (the branch is
+        #   unreachable, so `T.absurd` is correct). The caller suppresses the `absurd-reachable` diagnostic
+        #   in this case.
         def self.exhaustive?(call_node, scope)
           return false if scope.nil?
 
@@ -76,9 +62,8 @@ module Rigor
           arg_type = scope.type_of(arg)
           arg_type.equal?(Rigor::Type::Bot.instance) || arg_type.is_a?(Rigor::Type::Bot)
         rescue StandardError
-          # On synthetic / unrecognised nodes the typer may
-          # raise; treat as "can't prove unreachable" so the
-          # diagnostic fires conservatively.
+          # On synthetic / unrecognised nodes the typer may raise; treat as "can't prove unreachable" so
+          # the diagnostic fires conservatively.
           false
         end
       end

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/assertion_recognizer.rb

@@ -7,13 +7,10 @@ require_relative "type_translator"
 module Rigor
   module Plugin
     class Sorbet < Rigor::Plugin::Base
-      # Lifts Sorbet's type-assertion calls (`T.let`, `T.cast`,
-      # `T.must`, `T.must_because`, `T.unsafe`, `T.reveal_type`)
-      # into `FlowContribution` return-type contributions.
-      # ADR-11 slice 2 covered the original four; the
-      # `must_because` / `reveal_type` light follow-up extends
-      # the same module rather than splitting into a parallel
-      # recogniser.
+      # Lifts Sorbet's type-assertion calls (`T.let`, `T.cast`, `T.must`, `T.must_because`, `T.unsafe`,
+      # `T.reveal_type`) into `FlowContribution` return-type contributions. ADR-11 slice 2 covered the
+      # original four; the `must_because` / `reveal_type` light follow-up extends the same module rather
+      # than splitting into a parallel recogniser.
       #
       # | Sorbet form                  | Contribution                            |
       # | ---------------------------- | --------------------------------------- |
@@ -26,54 +23,39 @@ module Rigor
       # | `T.assert_type!(expr, T)`    | return type ← translated `T` + static subtype check |
       # | `T.bind(self, T)`            | return type ← `Constant[nil]` + post_return_fact narrowing self to translated `T` |
       #
-      # The Sorbet runtime's `T.let` / `T.cast` actually return
-      # the inner expression unchanged at runtime; their job is
-      # purely to *assert* a static type. From Rigor's static
-      # perspective the simplest faithful translation is "the
-      # call's return type IS the asserted type" — the call
-      # site's downstream uses see that type. This matches what
-      # `%a{rigor:v1:assert: x is T}` would do for an assignment
-      # in the surrounding scope.
+      # The Sorbet runtime's `T.let` / `T.cast` actually return the inner expression unchanged at runtime;
+      # their job is purely to *assert* a static type. From Rigor's static perspective the simplest
+      # faithful translation is "the call's return type IS the asserted type" — the call site's downstream
+      # uses see that type. This matches what `%a{rigor:v1:assert: x is T}` would do for an assignment in
+      # the surrounding scope.
       #
-      # `T.must_because` is `T.must` with a second-argument
-      # string explanation. The static behaviour is identical to
-      # `T.must` — strip `nil` from the inferred type — so the
-      # recogniser dispatches through the same path.
+      # `T.must_because` is `T.must` with a second-argument string explanation. The static behaviour is
+      # identical to `T.must` — strip `nil` from the inferred type — so the recogniser dispatches through
+      # the same path.
       #
-      # `T.reveal_type` is "diagnostic-only" in Sorbet: it
-      # passes the value through unchanged at runtime AND
-      # surfaces the inferred static type as a build-time
-      # message. The recogniser contributes the inferred type
-      # (so chained call sites still resolve as if the
-      # `T.reveal_type` wrapper weren't there); the plugin's
-      # `diagnostics_for_file` hook surfaces the
-      # `plugin.sorbet.reveal-type` `:info` message for human
-      # consumption.
+      # `T.reveal_type` is "diagnostic-only" in Sorbet: it passes the value through unchanged at runtime
+      # AND surfaces the inferred static type as a build-time message. The recogniser contributes the
+      # inferred type (so chained call sites still resolve as if the `T.reveal_type` wrapper weren't
+      # there); the plugin's `diagnostics_for_file` hook surfaces the `plugin.sorbet.reveal-type` `:info`
+      # message for human consumption.
       #
-      # `T.bind(self, T)` is recognised as block-scope self
-      # narrowing. The recogniser returns a contribution whose
-      # `post_return_facts` carries a `Fact(target_kind: :self)`
-      # so the engine's `apply_self_post_return_fact` narrows
-      # `scope.self_type` for the surrounding scope (in a block
-      # body, the rest of the block). The first argument MUST be
-      # a literal `Prism::SelfNode` — Sorbet rejects other
-      # receivers and the recogniser mirrors that. The runtime
-      # call returns nil, so the static return type is
-      # `Constant[nil]`.
+      # `T.bind(self, T)` is recognised as block-scope self narrowing. The recogniser returns a
+      # contribution whose `post_return_facts` carries a `Fact(target_kind: :self)` so the engine's
+      # `apply_self_post_return_fact` narrows `scope.self_type` for the surrounding scope (in a block
+      # body, the rest of the block). The first argument MUST be a literal `Prism::SelfNode` — Sorbet
+      # rejects other receivers and the recogniser mirrors that. The runtime call returns nil, so the
+      # static return type is `Constant[nil]`.
       module AssertionRecognizer
-        # Method names this recogniser claims as Sorbet
-        # assertions. The plugin checks call sites against this
-        # set before any catalog lookup so a `T.let` call
-        # inside an analysed file always resolves through this
-        # module.
+        # Method names this recogniser claims as Sorbet assertions. The plugin checks call sites against
+        # this set before any catalog lookup so a `T.let` call inside an analysed file always resolves
+        # through this module.
         SORBET_ASSERTIONS = %i[let cast must must_because unsafe reveal_type assert_type! bind].freeze
 
         module_function
 
         # @param call_node [Prism::CallNode]
         # @param scope [Rigor::Scope]
-        # @param plugin_id [String] used for the contribution's
-        #   `provenance.source_family`.
+        # @param plugin_id [String] used for the contribution's `provenance.source_family`.
         # @return [Rigor::FlowContribution, nil]
         def recognize(call_node:, scope:, plugin_id:)
           return nil unless TypeTranslator.sorbet_t_namespaced?(call_node.receiver)
@@ -97,20 +79,15 @@ module Rigor
           end
         end
 
-        # `T.bind(self, T)` recognition. Sorbet rejects any
-        # non-`self` receiver argument, and the recogniser
-        # mirrors that — calls like `T.bind(other, X)` fall
-        # through silently. The contribution carries:
+        # `T.bind(self, T)` recognition. Sorbet rejects any non-`self` receiver argument, and the
+        # recogniser mirrors that — calls like `T.bind(other, X)` fall through silently. The contribution
+        # carries:
         #
-        # - `return_type: Constant[nil]` — Sorbet's runtime
-        #   `T.bind` returns nil; chained calls would be a
+        # - `return_type: Constant[nil]` — Sorbet's runtime `T.bind` returns nil; chained calls would be a
         #   bug, but the typing stays accurate.
-        # - `post_return_facts: [Fact(target_kind: :self,
-        #   type: T)]` — the engine's
-        #   `apply_self_post_return_fact` narrows
-        #   `scope.self_type` for the surrounding scope. In a
-        #   block body, that scope is the block's own, so the
-        #   narrowing applies to the rest of the block —
+        # - `post_return_facts: [Fact(target_kind: :self, type: T)]` — the engine's
+        #   `apply_self_post_return_fact` narrows `scope.self_type` for the surrounding scope. In a block
+        #   body, that scope is the block's own, so the narrowing applies to the rest of the block —
         #   matching Sorbet's documented contract.
         def recognize_bind(call_node, plugin_id)
           first_arg = nth_argument(call_node, 0)
@@ -137,15 +114,11 @@ module Rigor
           )
         end
 
-        # `T.assert_type!(expr, T)` shares the typed-assertion
-        # contribution shape with `T.cast` (return is the
-        # asserted type), so the recogniser delegates the
-        # return-type half through `resolve_typed_assertion`.
-        # The static subtype check that distinguishes
-        # `assert_type!` from `cast` lives in the plugin's
-        # `diagnostics_for_file` hook (mirroring the
-        # absurd-recognizer pattern: record the call here, emit
-        # the diagnostic from the per-file walker).
+        # `T.assert_type!(expr, T)` shares the typed-assertion contribution shape with `T.cast` (return is
+        # the asserted type), so the recogniser delegates the return-type half through
+        # `resolve_typed_assertion`. The static subtype check that distinguishes `assert_type!` from
+        # `cast` lives in the plugin's `diagnostics_for_file` hook (mirroring the absurd-recognizer
+        # pattern: record the call here, emit the diagnostic from the per-file walker).
         def assert_type_check(call_node, scope)
           return nil if scope.nil?
 
@@ -162,14 +135,11 @@ module Rigor
           nil
         end
 
-        # `T.reveal_type(expr)` returns `expr` unchanged at
-        # runtime; the Sorbet-side semantics is "make the
-        # inferred static type visible to the user." The
-        # contribution mirrors `T.must` minus the nil-stripping:
-        # the call's return type is the inner expression's
-        # inferred type. The companion diagnostic is emitted by
-        # the plugin's `diagnostics_for_file` hook; this
-        # method handles the contribution only.
+        # `T.reveal_type(expr)` returns `expr` unchanged at runtime; the Sorbet-side semantics is "make
+        # the inferred static type visible to the user." The contribution mirrors `T.must` minus the
+        # nil-stripping: the call's return type is the inner expression's inferred type. The companion
+        # diagnostic is emitted by the plugin's `diagnostics_for_file` hook; this method handles the
+        # contribution only.
         def resolve_reveal_type(call_node, scope)
           inner = nth_argument(call_node, 0)
           return Rigor::Type::Combinator.untyped if inner.nil? || scope.nil?
@@ -177,17 +147,14 @@ module Rigor
           inner_type = scope.type_of(inner)
           inner_type || Rigor::Type::Combinator.untyped
         rescue StandardError
-          # Synthetic / virtual nodes can raise from
-          # `scope.type_of`; degrade gracefully so the dispatcher
+          # Synthetic / virtual nodes can raise from `scope.type_of`; degrade gracefully so the dispatcher
           # can still proceed with a benign untyped envelope.
           Rigor::Type::Combinator.untyped
         end
 
-        # `T.let(expr, T)` and `T.cast(expr, T)` share the same
-        # 2-argument shape: `arguments[1]` is the type
-        # expression. The first argument is opaque to slice 2 —
-        # we don't try to verify it at runtime; that's `srb tc`'s
-        # job and is out of scope per ADR-11.
+        # `T.let(expr, T)` and `T.cast(expr, T)` share the same 2-argument shape: `arguments[1]` is the
+        # type expression. The first argument is opaque to slice 2 — we don't try to verify it at runtime;
+        # that's `srb tc`'s job and is out of scope per ADR-11.
         def resolve_typed_assertion(call_node)
           type_arg = nth_argument(call_node, 1)
           return nil if type_arg.nil?
@@ -195,12 +162,9 @@ module Rigor
           TypeTranslator.translate(type_arg)
         end
 
-        # `T.must(expr)` strips `nil` from `expr`'s inferred
-        # type. The call's target type is therefore
-        # `inferred(expr) - Constant[nil]`. Falls back to the
-        # untyped envelope when the inferred shape is itself
-        # `Dynamic[top]` or when no scope is available
-        # (synthetic / virtual-node call sites).
+        # `T.must(expr)` strips `nil` from `expr`'s inferred type. The call's target type is therefore
+        # `inferred(expr) - Constant[nil]`. Falls back to the untyped envelope when the inferred shape is
+        # itself `Dynamic[top]` or when no scope is available (synthetic / virtual-node call sites).
         def resolve_must(call_node, scope)
           inner = nth_argument(call_node, 0)
           return nil if inner.nil? || scope.nil?
@@ -210,18 +174,15 @@ module Rigor
 
           strip_nil(inner_type)
         rescue StandardError
-          # `scope.type_of` may raise on synthetic nodes; degrade
-          # to "no contribution" rather than crash the dispatcher.
+          # `scope.type_of` may raise on synthetic nodes; degrade to "no contribution" rather than crash
+          # the dispatcher.
           nil
         end
 
-        # Removes `nil` (`Constant[nil]`) from `type` using the
-        # `Difference` carrier. Idempotent on shapes that don't
-        # contain nil — the resulting `Difference[base, removed]`
-        # collapses to `base` if `base` already excludes the
-        # removed value, but the simple form here is good enough
-        # for slice 2; the precise normalisation lands when the
-        # Difference carrier gets full algebraic support.
+        # Removes `nil` (`Constant[nil]`) from `type` using the `Difference` carrier. Idempotent on shapes
+        # that don't contain nil — the resulting `Difference[base, removed]` collapses to `base` if `base`
+        # already excludes the removed value, but the simple form here is good enough for slice 2; the
+        # precise normalisation lands when the Difference carrier gets full algebraic support.
         def strip_nil(type)
           Rigor::Type::Combinator.difference(
             type, Rigor::Type::Combinator.constant_of(nil)

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/catalog.rb

@@ -3,28 +3,22 @@
 module Rigor
   module Plugin
     class Sorbet < Rigor::Plugin::Base
-      # Per-run table of method signatures keyed by the
-      # `(class_name, method_name, kind)` triple. Built by
-      # {CatalogWalker} during the plugin's lazy pre-walk; read
-      # by the plugin's `dynamic_return` rule at every gated call site.
+      # Per-run table of method signatures keyed by the `(class_name, method_name, kind)` triple. Built by
+      # {CatalogWalker} during the plugin's lazy pre-walk; read by the plugin's `dynamic_return` rule at
+      # every gated call site.
       #
-      # The catalog is mutable while it is being built, then
-      # frozen via {#freeze!} before the first read. Construction
-      # mutability is intentional — slice 1 builds the catalog
-      # incrementally as the walker visits each project file —
-      # but consumers MUST treat the catalog as read-only.
+      # The catalog is mutable while it is being built, then frozen via {#freeze!} before the first read.
+      # Construction mutability is intentional — slice 1 builds the catalog incrementally as the walker
+      # visits each project file — but consumers MUST treat the catalog as read-only.
       class Catalog
-        # Frozen empty bucket reused for classes that have no
-        # recorded mixins. Avoids allocating a fresh Hash on
-        # every `mixins_for` query.
+        # Frozen empty bucket reused for classes that have no recorded mixins. Avoids allocating a fresh
+        # Hash on every `mixins_for` query.
         EMPTY_MIXINS = { include: [].freeze, extend: [].freeze }.freeze
 
         def initialize
           @entries = {}
-          # ADR-11 slice 8 — per-class mixin declarations
-          # collected by `CatalogWalker`. Lookup-time chain
-          # traversal lifts sigs declared on a mixed-in
-          # module to call sites on the host class.
+          # ADR-11 slice 8 — per-class mixin declarations collected by `CatalogWalker`. Lookup-time chain
+          # traversal lifts sigs declared on a mixed-in module to call sites on the host class.
           @mixins = {}
           @frozen_after_build = false
         end
@@ -37,13 +31,11 @@ module Rigor
           @entries[key] = signature
         end
 
-        # @param class_name [String] the class / module that
-        #   carries the mixin (`class Post; include Foo; end`
-        #   records under `"Post"`).
+        # @param class_name [String] the class / module that carries the mixin (`class Post; include Foo;
+        #   end` records under `"Post"`).
         # @param kind [:include, :extend]
-        # @param module_name [String] the textual name of the
-        #   mixed-in module as it appeared at the include /
-        #   extend site (`"Foo"`, `"Foo::Bar"`, `"::Foo"`).
+        # @param module_name [String] the textual name of the mixed-in module as it appeared at the
+        #   include / extend site (`"Foo"`, `"Foo::Bar"`, `"::Foo"`).
         def record_mixin(class_name:, kind:, module_name:)
           raise "Catalog already finalised" if @frozen_after_build
 
@@ -69,9 +61,8 @@ module Rigor
         end
 
         # @param class_name [String]
-        # @return [Hash{Symbol => Array<String>}] frozen mapping
-        #   `{ include: [...], extend: [...] }`. Returns
-        #   {EMPTY_MIXINS} when no mixins were recorded.
+        # @return [Hash{Symbol => Array<String>}] frozen mapping `{ include: [...], extend: [...] }`.
+        #   Returns {EMPTY_MIXINS} when no mixins were recorded.
         def mixins_for(class_name)
           @mixins[class_name] || EMPTY_MIXINS
         end
@@ -80,16 +71,12 @@ module Rigor
           @entries.empty?
         end
 
-        # ADR-52 slice 4 — the distinct method names the catalog
-        # carries at least one signature for, across every
-        # `(class_name, kind)` owner. Feeds the plugin's run-time
-        # `dynamic_return methods:` name gate: the engine only
-        # consults the plugin for a call whose name appears here
-        # (or in the static assertion vocabulary), and the
-        # precise `(class, kind)` lookup stays in the rule block.
-        # Computed fresh per call — the plugin memoises the
-        # resolved set, and `freeze!` freezes the catalog itself
-        # so a lazy memo ivar here would raise.
+        # ADR-52 slice 4 — the distinct method names the catalog carries at least one signature for,
+        # across every `(class_name, kind)` owner. Feeds the plugin's run-time `dynamic_return methods:`
+        # name gate: the engine only consults the plugin for a call whose name appears here (or in the
+        # static assertion vocabulary), and the precise `(class, kind)` lookup stays in the rule block.
+        # Computed fresh per call — the plugin memoises the resolved set, and `freeze!` freezes the
+        # catalog itself so a lazy memo ivar here would raise.
         #
         # @return [Array<Symbol>]
         def method_names