rigortype 0.0.8 → 0.1.0

data/lib/rigor/flow_contribution/merger.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Composes any number of {FlowContribution} bundles into a
+    # single {MergeResult} per ADR-2 § "Plugin Contribution
+    # Merging". The merger is the **single point of integration**
+    # the analyzer uses to combine contributions from built-in
+    # narrowing rules, `RBS::Extended` annotations, and plugins;
+    # slice 4 routes the existing internal narrowing through it
+    # and slice 6 wires plugin-side cache producers around it.
+    #
+    # ## Authority tiers
+    #
+    # - Tier 0: `:builtin` — Core Ruby semantics and accepted RBS
+    #   contracts. Authoritative; lower tiers may not contradict.
+    # - Tier 1: `:rbs_extended` (`RBS::Extended` directive bundles,
+    #   v0.0.9 group D reference impl) and `:generated` (generated
+    #   signatures / metadata).
+    # - Tier 2: `:plugin` and `plugin.<id>` source families.
+    # - Tier 3: anything else — treated as the lowest tier.
+    #
+    # Within a tier, contributions are merged in deterministic
+    # order: provenance-supplied `plugin_id` alphabetical (nil
+    # plugin ids sort first to keep `:rbs_extended` / `:generated`
+    # pre-plugin contributions stable), then by their original
+    # input position as the final tie-break.
+    #
+    # ## Composition rules (ADR-2)
+    #
+    # - `:return_type` — Intersect via `Type::Combinator.intersection`;
+    #   collapse to bot raises `:return_type_collapse`.
+    # - `:truthy_fact` / `:falsey_fact` / `:post_return_fact` —
+    #   Edge-local; accumulate while deduping by payload equality.
+    # - `:mutation` / `:invalidation` / `:role` — Union; dedupe by
+    #   equality.
+    # - `:exception` — Single-valued. Two non-`nil` non-equal
+    #   exceptional effects raise `:exceptional_disagreement`.
+    #
+    # ## Cross-tier contradictions
+    #
+    # Lower tiers may refine higher tiers but must not weaken them.
+    # Slice 3 surfaces contradictions through `:lower_tier_contradiction`
+    # when:
+    #
+    # - the higher tier already pinned a `return_type` and a lower
+    #   tier's intersection collapses to `bot`;
+    # - the higher tier set `exceptional` to a non-`nil` value and a
+    #   lower tier disagrees.
+    #
+    # In every conflict case the result keeps the higher-tier value
+    # for that slot, records a {Conflict} with both provenances, and
+    # continues processing the remaining slots / contributions.
+    module Merger # rubocop:disable Metrics/ModuleLength
+      AUTHORITY_TIERS = {
+        builtin: 0,
+        rbs_extended: 1,
+        generated: 1
+      }.freeze
+
+      module_function
+
+      # @param contributions [Array<FlowContribution>]
+      # @return [MergeResult]
+      def merge(contributions)
+        contributions = Array(contributions)
+        return MergeResult.new if contributions.empty?
+
+        ordered = order_contributions(contributions)
+        state = MergeState.new
+        ordered.each do |contribution|
+          tier = tier_for(contribution.provenance)
+          fold_into(state, contribution, tier)
+        end
+        state.to_result
+      end
+
+      def tier_for(provenance)
+        family = provenance.respond_to?(:source_family) ? provenance.source_family : nil
+        return AUTHORITY_TIERS[family] if AUTHORITY_TIERS.key?(family)
+        return 2 if family == :plugin || family.to_s.start_with?("plugin.")
+
+        3
+      end
+
+      class << self
+        private
+
+        def order_contributions(contributions)
+          # Stable sort: tier ascending, then provenance plugin_id
+          # alphabetical (nil first), then original input position.
+          contributions.each_with_index
+                       .sort_by { |c, i| [tier_for(c.provenance), plugin_id_key(c.provenance), i] }
+                       .map { |c, _| c }
+        end
+
+        def plugin_id_key(provenance)
+          id = provenance.respond_to?(:plugin_id) ? provenance.plugin_id : nil
+          [id.nil? ? 0 : 1, id.to_s]
+        end
+
+        def fold_into(state, contribution, tier)
+          state.add_provenance(contribution.provenance)
+          fold_return_type(state, contribution, tier)
+          fold_facts(state, contribution)
+          fold_effects(state, contribution)
+          fold_exceptional(state, contribution, tier)
+          fold_role_conformance(state, contribution)
+        end
+
+        def fold_return_type(state, contribution, tier) # rubocop:disable Metrics/AbcSize
+          incoming = contribution.return_type
+          return if incoming.nil?
+
+          if state.return_type.nil?
+            state.return_type = incoming
+            state.return_type_tier = tier
+            state.return_type_provenance = contribution.provenance
+            return
+          end
+
+          if intersection_empty?(state.return_type, incoming)
+            reason = tier > state.return_type_tier ? :lower_tier_contradiction : :return_type_collapse
+            state.conflicts << build_conflict(
+              target: :return,
+              edge: :normal,
+              kind: :return_type,
+              reason: reason,
+              provenances: [state.return_type_provenance, contribution.provenance],
+              message: return_type_conflict_message(reason, state.return_type, incoming)
+            )
+            return
+          end
+
+          state.return_type = Rigor::Type::Combinator.intersection(state.return_type, incoming)
+          state.return_type_tier = [state.return_type_tier, tier].min
+        end
+
+        # Two types' intersection collapses to bot when neither
+        # accepts the other under gradual mode — i.e. the value
+        # domains are disjoint. `Rigor::Type::Combinator.intersection`
+        # itself does not collapse incompatible nominals (`String ∩
+        # Integer` builds a structurally-empty `Intersection`
+        # carrier), so the merger checks the disjointness condition
+        # directly via the `accepts` trinary.
+        def intersection_empty?(lhs, rhs)
+          return false if lhs.equal?(rhs)
+
+          lhs_no = lhs.accepts(rhs).no?
+          rhs_no = rhs.accepts(lhs).no?
+          lhs_no && rhs_no
+        rescue StandardError
+          false
+        end
+
+        def fold_facts(state, contribution)
+          accumulate(state.truthy_facts, contribution.truthy_facts)
+          accumulate(state.falsey_facts, contribution.falsey_facts)
+          accumulate(state.post_return_facts, contribution.post_return_facts)
+        end
+
+        def fold_effects(state, contribution)
+          accumulate(state.mutations, contribution.mutations)
+          accumulate(state.invalidations, contribution.invalidations)
+        end
+
+        def fold_exceptional(state, contribution, tier)
+          incoming = contribution.exceptional
+          return if incoming.nil?
+
+          if state.exceptional.nil?
+            state.exceptional = incoming
+            state.exceptional_tier = tier
+            state.exceptional_provenance = contribution.provenance
+            return
+          end
+
+          return if state.exceptional == incoming
+
+          reason = tier > state.exceptional_tier ? :lower_tier_contradiction : :exceptional_disagreement
+          state.conflicts << build_conflict(
+            target: :raise,
+            edge: :exceptional,
+            kind: :exception,
+            reason: reason,
+            provenances: [state.exceptional_provenance, contribution.provenance],
+            message: "exceptional effect disagreement: #{state.exceptional.inspect} vs #{incoming.inspect}"
+          )
+        end
+
+        def fold_role_conformance(state, contribution)
+          accumulate(state.role_conformance, contribution.role_conformance)
+        end
+
+        def accumulate(target, incoming)
+          Array(incoming).each do |item|
+            target << item unless target.include?(item)
+          end
+        end
+
+        def build_conflict(target:, edge:, kind:, reason:, provenances:, message:) # rubocop:disable Metrics/ParameterLists
+          Conflict.new(target: target, edge: edge, kind: kind, reason: reason,
+                       provenances: provenances, message: message)
+        end
+
+        def return_type_conflict_message(reason, lhs, rhs)
+          case reason
+          when :return_type_collapse
+            "return-type intersection collapses to bot: #{describe(lhs)} vs #{describe(rhs)}"
+          when :lower_tier_contradiction
+            "lower-tier return-type #{describe(rhs)} contradicts higher-tier proof #{describe(lhs)}"
+          end
+        end
+
+        def describe(type)
+          if type.respond_to?(:describe)
+            type.describe(:short)
+          else
+            type.inspect
+          end
+        rescue StandardError
+          type.inspect
+        end
+      end
+
+      # Internal accumulator carried through a single merge call.
+      # Not part of the public API; folds into a {MergeResult} at
+      # the end via {#to_result}.
+      class MergeState
+        attr_accessor :return_type, :return_type_tier, :return_type_provenance,
+                      :exceptional, :exceptional_tier, :exceptional_provenance
+        attr_reader :truthy_facts, :falsey_facts, :post_return_facts,
+                    :mutations, :invalidations, :role_conformance,
+                    :provenances, :conflicts
+
+        def initialize
+          @return_type = nil
+          @return_type_tier = nil
+          @return_type_provenance = nil
+          @truthy_facts = []
+          @falsey_facts = []
+          @post_return_facts = []
+          @mutations = []
+          @invalidations = []
+          @exceptional = nil
+          @exceptional_tier = nil
+          @exceptional_provenance = nil
+          @role_conformance = []
+          @provenances = []
+          @conflicts = []
+        end
+
+        def add_provenance(provenance)
+          @provenances << provenance
+        end
+
+        def to_result
+          MergeResult.new(
+            return_type: @return_type,
+            truthy_facts: @truthy_facts,
+            falsey_facts: @falsey_facts,
+            post_return_facts: @post_return_facts,
+            mutations: @mutations,
+            invalidations: @invalidations,
+            exceptional: @exceptional,
+            role_conformance: @role_conformance,
+            provenances: @provenances,
+            conflicts: @conflicts
+          )
+        end
+      end
+      private_constant :MergeState
+    end
+  end
+end

data/lib/rigor/flow_contribution.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "flow_contribution/element"
+
+module Rigor
+  # The public packaging of a flow contribution at a single call edge.
+  # Plugins, `RBS::Extended` annotations, and built-in narrowing rules
+  # all hand the analyzer this same bundle shape; the inference engine
+  # merges contributions through the policy described in
+  # [ADR-2 § "Plugin Contribution Merging"](../../docs/adr/2-extension-api.md)
+  # rather than letting any one source override another silently.
+  #
+  # Eight content slots plus a {Provenance} block. A slot left as `nil`
+  # (or, for collection-shaped slots, an empty collection) means the
+  # contribution does not assert anything in that dimension; the merge
+  # policy treats it as absent.
+  #
+  # The struct is the only shape plugin authors need to learn. Richer
+  # or more permissive shapes are not part of the first public
+  # contract — see ADR-2 § "Flow Contribution Bundle" for the binding
+  # definition.
+  #
+  # The element-list flattening (`to_element_list`) ADR-2 mentions is
+  # intentionally not implemented yet: it is the analyzer-internal
+  # bookkeeping behind the merge policy and will land alongside the
+  # plugin contribution merger in v0.1.0. Plugin authors should not
+  # rely on it.
+  class FlowContribution
+    # Provenance carries the metadata every contribution needs for
+    # diagnostic attribution and cache invalidation. `source_family`
+    # mirrors {Rigor::Analysis::Diagnostic::DEFAULT_SOURCE_FAMILY};
+    # `descriptor` is the {Rigor::Cache::Descriptor} this
+    # contribution attaches to (or `nil` when the contribution does
+    # not need its own cache slice).
+    Provenance = Data.define(:source_family, :plugin_id, :node, :descriptor) do
+      def self.builtin
+        new(source_family: :builtin, plugin_id: nil, node: nil, descriptor: nil)
+      end
+    end
+
+    SLOT_NAMES = %i[
+      return_type
+      truthy_facts
+      falsey_facts
+      post_return_facts
+      mutations
+      invalidations
+      exceptional
+      role_conformance
+    ].freeze
+
+    attr_reader(*SLOT_NAMES, :provenance)
+
+    # @param return_type [Object, nil] normal-edge return type. Use
+    #   `nil` when the contribution does not refine the return type
+    #   selected from the RBS contract.
+    # @param truthy_facts [Array, nil] facts that hold only on the
+    #   truthy control-flow edge. Edge-local: a truthy-edge fact does
+    #   NOT imply its falsey-edge complement (ADR-2 § "Plugin
+    #   Contribution Merging").
+    # @param falsey_facts [Array, nil] dual of `truthy_facts`.
+    # @param post_return_facts [Array, nil] facts that hold after the
+    #   call returns normally on every edge — the carrier for
+    #   assertion-style contributions.
+    # @param mutations [Array, nil] receiver and argument mutation
+    #   effects.
+    # @param invalidations [Array, nil] targeted fact invalidations
+    #   beyond what mutation effects already imply.
+    # @param exceptional [Object, nil] non-returning, raising, or
+    #   unreachable effect.
+    # @param role_conformance [Array, nil] capability-role conformance
+    #   facts the contribution provides.
+    # @param provenance [Provenance] source-family, plugin-id, node,
+    #   and cache-descriptor metadata. Defaults to `Provenance.builtin`.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(return_type: nil, truthy_facts: nil, falsey_facts: nil,
+                   post_return_facts: nil, mutations: nil, invalidations: nil,
+                   exceptional: nil, role_conformance: nil,
+                   provenance: Provenance.builtin)
+      # rubocop:enable Metrics/ParameterLists
+      @return_type = return_type
+      @truthy_facts = freeze_collection(truthy_facts)
+      @falsey_facts = freeze_collection(falsey_facts)
+      @post_return_facts = freeze_collection(post_return_facts)
+      @mutations = freeze_collection(mutations)
+      @invalidations = freeze_collection(invalidations)
+      @exceptional = exceptional
+      @role_conformance = freeze_collection(role_conformance)
+      @provenance = provenance
+      freeze
+    end
+
+    # @return [Boolean] true when every content slot is unset (nil or
+    #   an empty collection). Provenance does not count toward
+    #   emptiness — an empty bundle still carries source attribution.
+    def empty?
+      SLOT_NAMES.all? { |slot| slot_empty?(public_send(slot)) }
+    end
+
+    def to_h
+      SLOT_NAMES.each_with_object(provenance: provenance.to_h) do |slot, acc|
+        acc[slot] = public_send(slot)
+      end
+    end
+
+    # Flattens this bundle into a tagged element list keyed by
+    # `(target, edge, kind)`. The flattening is mechanical and
+    # round-trippable through {Merger.merge}: feeding the result
+    # back through the merger produces an equivalent bundle.
+    #
+    # Layout:
+    #
+    # | slot                | edge          | kind                | target                  |
+    # | --------------------|---------------|---------------------|-------------------------|
+    # | return_type         | normal        | return_type         | :return                 |
+    # | truthy_facts        | truthy        | truthy_fact         | (per-fact target)       |
+    # | falsey_facts        | falsey        | falsey_fact         | (per-fact target)       |
+    # | post_return_facts   | post_return   | post_return_fact    | (per-fact target)       |
+    # | mutations           | normal        | mutation            | (per-mutation target)   |
+    # | invalidations       | normal        | invalidation        | (per-fact target)       |
+    # | exceptional         | exceptional   | exception           | :raise                  |
+    # | role_conformance    | normal        | role                | (per-role target)       |
+    #
+    # @return [Array<Element>]
+    def to_element_list # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      elements = []
+      elements << element_for(:return, :normal, :return_type, return_type) unless return_type.nil?
+      Array(truthy_facts).each { |fact| elements << element_for(fact_target(fact), :truthy, :truthy_fact, fact) }
+      Array(falsey_facts).each { |fact| elements << element_for(fact_target(fact), :falsey, :falsey_fact, fact) }
+      Array(post_return_facts).each do |fact|
+        elements << element_for(fact_target(fact), :post_return, :post_return_fact, fact)
+      end
+      Array(mutations).each { |m| elements << element_for(fact_target(m), :normal, :mutation, m) }
+      Array(invalidations).each { |i| elements << element_for(fact_target(i), :normal, :invalidation, i) }
+      elements << element_for(:raise, :exceptional, :exception, exceptional) unless exceptional.nil?
+      Array(role_conformance).each { |r| elements << element_for(fact_target(r), :normal, :role, r) }
+      elements.freeze
+    end
+
+    def ==(other)
+      other.is_a?(FlowContribution) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    private
+
+    def element_for(target, edge, kind, payload)
+      Element.new(target: target, edge: edge, kind: kind, payload: payload, provenance: provenance)
+    end
+
+    # Best-effort target extraction. Payloads that expose a
+    # `#target` accessor (typed-fact carriers, mutation effects)
+    # provide their own; everything else falls through with the
+    # payload itself as the merge key, which keeps deduplication
+    # well-defined for opaque entries.
+    def fact_target(payload)
+      return payload.target if payload.respond_to?(:target)
+
+      payload
+    end
+
+    def freeze_collection(value)
+      return nil if value.nil?
+
+      value.dup.freeze
+    end
+
+    def slot_empty?(value)
+      return true if value.nil?
+      return value.empty? if value.respond_to?(:empty?)
+
+      false
+    end
+  end
+end

data/lib/rigor/inference/block_parameter_binder.rb

@@ -34,6 +34,12 @@ module Rigor
     # `[1, 2, 3].each { _1 + _2 }` sees `_1`/`_2` typed identically
     # to their explicit `|x, y|` counterparts.
     #
+    # The `it` implicit parameter (Ruby 3.4+) is bound from
+    # `Prism::ItParametersNode`. It is the single-argument cousin of
+    # `_1`: the binder produces `{ it: expected_param_types[0] }` so
+    # the body's `Prism::ItLocalVariableReadNode` lookup sees the same
+    # type as the explicit `|x|` form would.
+    #
     # Block-local declarations after `;` (e.g., `|x; y, z|`) are
     # still skipped — they are explicitly block-local, so the outer
     # scope MUST NOT observe them and the binder leaves them unbound.
@@ -65,6 +71,8 @@ module Rigor
         case params_root
         when Prism::NumberedParametersNode
           bind_numbered_parameters(params_root)
+        when Prism::ItParametersNode
+          bind_it_parameter
         when Prism::BlockParametersNode
           bind_block_parameters(params_root)
         else
@@ -88,6 +96,13 @@ module Rigor
         bindings
       end
 
+      # `{ it.foo }` — Ruby 3.4 `it` is a single-argument implicit
+      # parameter. Always binds the symbol `:it`; `ItLocalVariableReadNode`
+      # in the body looks the binding up by name.
+      def bind_it_parameter
+        { it: positional_type_at(0) }
+      end
+
       def bind_block_parameters(params_root)
         params_node = params_root.parameters
         return {} if params_node.nil?

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Encoding` catalog. Singleton — load once, consult during
+      # dispatch.
+      #
+      # Encoding instances are deep-frozen value objects: once
+      # registered, their `name` / `dummy?` / `ascii_compatible?`
+      # slots never change and the C bodies for the per-instance
+      # methods are pure. The C-body classifier therefore lands
+      # every instance method as `:leaf` correctly.
+      #
+      # The blocklist focuses on the *singleton* surface where the
+      # hidden state is the process-wide encoding registry. Every
+      # method classified `:leaf` on the singleton actually reads
+      # (or, for the setters, writes) a global, so a hypothetical
+      # `Constant<Encoding>`-class receiver MUST NOT fold them
+      # against the analyzer process's registry — what UTF-8's
+      # alias list is in the analyzer is not necessarily what it
+      # is in the analysed program.
+      ENCODING_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/encoding.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Encoding" => Set[
+            # Defence-in-depth: mirrors range_catalog.rb /
+            # complex_catalog.rb. Encoding does not currently
+            # expose a public `initialize_copy` (Encoding objects
+            # are deep-frozen and #dup is a no-op), but the
+            # convention keeps the door closed against future
+            # CRuby changes that would leak a copy-mutator.
+            :initialize_copy,
+            :hash,
+            :eql?,
+            # `Encoding.find(name)` walks the global encoding
+            # registry. Pure with respect to its argument but
+            # the registry itself can drift (load-order, locale,
+            # process-wide `default_external=` calls), so a
+            # constant-fold would lock in the analyzer's view.
+            :find,
+            # `Encoding.list` / `Encoding.aliases` /
+            # `Encoding.name_list` enumerate the same global
+            # registry. Same reasoning as `find` — the values
+            # are not guaranteed to match the analysed program's
+            # registry.
+            :list,
+            :aliases,
+            :name_list,
+            # Global-default mutators. `MethodCatalog#blocked?`
+            # only auto-blocks `!`-suffixed selectors, so we MUST
+            # list these explicitly: each writes the process-wide
+            # default-encoding slot read by `default_external` /
+            # `default_internal`.
+            :default_external=,
+            :default_internal=
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Exception` catalog. Singleton — load once, consult during
+      # dispatch.
+      #
+      # Exception is the base of every Ruby error class (RuntimeError,
+      # StandardError, KeyError, …). The Init_Exception block in
+      # `references/ruby/error.c` registers the entire hierarchy in
+      # one pass, so the YAML carries 27 classes — but only the base
+      # `Exception` row is wired into `CATALOG_BY_CLASS` for v0.0.5.
+      # A `RuntimeError` receiver hits the Exception arm via
+      # `is_a?(Exception)` and the catalog answers with the base-class
+      # entries; subclass-specific methods (`KeyError#receiver`,
+      # `NameError#name`, …) intentionally miss the lookup until a
+      # later slice routes per-subclass class_names.
+      #
+      # The catalog tier here is *defence in depth* — every base
+      # method that could plausibly fold has been weighed against the
+      # robustness principle (strict on returns) and either left
+      # `:dispatch` / `:mutates_self` (in which case the catalog
+      # already declines) or blocklisted because the static classifier
+      # missed an indirect side effect. The remaining `:leaf` method
+      # that DOES fold is `#cause`, a pure accessor.
+      EXCEPTION_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/exception.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Exception" => Set[
+            # `exc_initialize` writes `mesg` / `backtrace` ivars on
+            # self via `rb_ivar_set` — the C-body classifier missed
+            # the indirect mutator because the helpers are not in
+            # its regex. Blocklisted so a hypothetical future
+            # `Constant<Exception>` carrier cannot fold an aliasing
+            # constructor through the catalog.
+            :initialize,
+            # `exc_exception` either returns self (no-arg) or calls
+            # `rb_obj_clone` + `exc_initialize_internal` on the
+            # clone — the clone branch mutates fresh state through
+            # the same indirect helpers as `:initialize`. Conservative
+            # blocklist; the cost is one folded no-arg call.
+            :exception,
+            # `exc_detailed_message` formats with platform / locale
+            # data (highlight markers depend on `$stderr.tty?` via
+            # the keyword arg default and `rb_io_tty_p`). Folding
+            # would freeze a value that depends on the calling
+            # process's stderr state.
+            :detailed_message,
+            # `exc_backtrace` reads the captured frame list, which
+            # depends on where the exception was raised — context
+            # the static fold tier cannot reproduce.
+            :backtrace,
+            # Same rationale as `:backtrace`; `Thread::Backtrace::Location`
+            # objects are runtime artefacts.
+            :backtrace_locations,
+            # `exc_set_backtrace` mutates the @backtrace ivar via
+            # `rb_ivar_set` — another indirect mutator the classifier
+            # missed.
+            :set_backtrace,
+            # `initialize_copy` is blocklisted by convention so a
+            # hypothetical future `Constant<Exception>` carrier
+            # cannot fold an aliasing copy through the catalog.
+            :initialize_copy,
+            # Defensive entries for the universal mutation surface.
+            # Object-identity hashing on a constant carrier is fine,
+            # but `eql?` on Exception delegates to `==` (dispatch);
+            # blocking both keeps the constant-fold tier honest.
+            :hash,
+            :eql?
+          ],
+          # `Exception.to_tty?` (singleton) calls
+          # `rb_io_tty_p($stderr)`; its return depends on the
+          # process's stderr state at runtime, never on compile-time
+          # arguments. The catalog tier today only consults
+          # `mutating_selectors` for instance-receiver dispatches via
+          # `CATALOG_BY_CLASS`, so this row is documentation-grade —
+          # it records the soundness rationale for any future slice
+          # that wires the singleton path through the catalog.
+          "Exception.singleton" => Set[
+            :to_tty?
+          ]
+        }
+      )
+    end
+  end
+end