rigortype 0.1.15 → 0.1.17

data/lib/rigor/environment/rbs_loader.rb

@@ -30,6 +30,24 @@ module Rigor
     # See docs/internal-spec/inference-engine.md for the binding contract.
     # rubocop:disable Metrics/ClassLength
     class RbsLoader
+      # Buffer name stamped on the `module` declarations synthesized by
+      # {.synthesize_missing_namespaces}. Re-read off the built env by
+      # {#synthesized_namespaces} so the analysis layer can surface an
+      # `:info` diagnostic naming the project's malformed-RBS namespaces
+      # — robust across the marshalled env cache, since the sentinel
+      # rides along on each synthetic declaration's location.
+      SYNTHETIC_NAMESPACE_BUFFER = "(rigor: synthesized namespaces)"
+
+      # Buffer name stamped on the stub `class` / `module` declarations
+      # synthesized by {.stub_missing_referenced_types} for types the
+      # project's RBS references but no loaded signature declares.
+      # {#synthesized_stub_types} reads them back off the built env (so
+      # the answer survives the marshalled env cache), and
+      # {#synthesized_type_names} folds them together with the
+      # namespace stubs into the set {MethodDispatcher} resolves to
+      # `Dynamic[Top]` (no false `call.undefined-method`).
+      SYNTHETIC_STUB_BUFFER = "(rigor: synthesized stub types)"
+
       class << self
         def default
           @default ||= new.freeze
@@ -72,7 +90,172 @@ module Rigor
           end
           env = RBS::Environment.from_loader(rbs_loader)
           add_virtual_rbs(env, virtual_rbs)
-          env.resolve_type_names
+          synthesize_missing_namespaces(env)
+          resolved = env.resolve_type_names
+          stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
+        end
+
+        # ADR-5 robustness, second tier. A project `signature_paths:`
+        # RBS that *references* a type no loaded signature declares —
+        # `def x: () -> DRb::DRbServer` when the `drb` RBS is not
+        # available, or a stale reference to its own removed
+        # `Textbringer::EditorError` — makes
+        # `RBS::DefinitionBuilder#build_instance` raise
+        # `NoTypeFoundError`, and (per RBS's all-or-nothing per-class
+        # build) that single unresolved reference takes down EVERY
+        # method on the class, not just the one signature. Observed on
+        # shugo/textbringer: one `DRb::DRbServer` reference left the
+        # whole `Textbringer::Commands` module — including its
+        # 186-call-site `define_command` DSL — resolving as
+        # `Dynamic[Top]`.
+        #
+        # We synthesize an empty stub for each such referenced-but-
+        # undeclared type so the rest of the class builds. A leaf type
+        # is stubbed as `class`, its enclosing namespaces as `module`.
+        # Stubbed types carry no methods, so a call against a value of
+        # a stubbed type would otherwise mis-fire `call.undefined-method`;
+        # {MethodDispatcher} consults {#synthesized_type_names} and
+        # resolves such calls to `Dynamic[Top]` instead (the same
+        # no-false-positive contract as the dependency-source tier).
+        #
+        # Detection re-uses RBS's own builder (correct by construction):
+        # build every PROJECT class and read the missing name out of the
+        # raised error. Bounded to `signature_paths` classes (stdlib /
+        # vendored RBS is well-formed) and to {MAX_STUB_PASSES}
+        # iterations — a fresh stub can expose a deeper reference the
+        # first build error hid, but empty stubs reference nothing, so
+        # the fixpoint converges quickly.
+        MAX_STUB_PASSES = 5
+
+        def stub_missing_referenced_types(base_env, resolved, project_files)
+          return resolved if project_files.empty?
+
+          MAX_STUB_PASSES.times do
+            missing = unresolved_referenced_types(resolved, project_files)
+            break if missing.empty?
+
+            append_stub_declarations(base_env, missing)
+            resolved = base_env.resolve_type_names
+          end
+          resolved
+        end
+
+        # Robustness (ADR-5): a project whose RBS declares qualified
+        # names (`class Foo::Bar`) without ever declaring the enclosing
+        # namespace (`module Foo`) is invalid by upstream RBS rules —
+        # `RBS::DefinitionBuilder#build_instance` raises
+        # `NoTypeFoundError: Could not find ::Foo`, which the loader's
+        # fail-soft rescue turns into a silent dispatch miss (every
+        # method on every such class degrades to `Dynamic[Top]`). This
+        # is a common authoring mistake (e.g. shugo/textbringer ships a
+        # `sig/` that `rbs validate` itself rejects). Rather than let an
+        # otherwise-usable signature set contribute nothing, synthesize
+        # an empty `module` declaration for each undeclared enclosing
+        # namespace so the definitions build. We only ever add names
+        # that are absent — a genuinely-declared namespace (module or
+        # class, here or in a loaded gem) is left untouched.
+        def synthesize_missing_namespaces(env)
+          missing = collect_missing_namespaces(env)
+          return if missing.empty?
+
+          source = missing.map { |name| "module #{name}\nend\n" }.join
+          buffer = ::RBS::Buffer.new(name: SYNTHETIC_NAMESPACE_BUFFER, content: source)
+          _, directives, decls = ::RBS::Parser.parse_signature(buffer)
+          env.add_source(::RBS::Source::RBS.new(buffer, directives || [], decls || []))
+        rescue ::RBS::BaseError
+          # Fail-soft: synthesis is an opportunistic uplift, never a
+          # hard requirement. A parse failure here just leaves the env
+          # as it was (dispatch misses on the affected classes).
+          nil
+        end
+
+        # Returns the `::`-stripped names of every enclosing namespace
+        # that some declaration references but no declaration defines,
+        # shallowest-first so the synthesized source declares `Foo`
+        # before `Foo::Bar`.
+        def collect_missing_namespaces(env)
+          declared = env.class_decls.keys.to_set
+          missing = {}
+          env.class_decls.each_key do |type_name|
+            path = type_name.namespace.path
+            path.each_index do |i|
+              prefix = path[0..i]
+              full = ::RBS::TypeName.parse("::#{prefix.join('::')}")
+              missing[prefix.join("::")] = prefix.length unless declared.include?(full)
+            end
+          end
+          missing.sort_by { |_name, depth| depth }.map(&:first)
+        end
+
+        # The absolute paths of every `.rbs` file under the project's
+        # `signature_paths:` (NOT vendored / stdlib RBS — those are
+        # well-formed, so attempting to build them would only waste
+        # time). Used to scope the referenced-type build sweep.
+        def project_sig_files(signature_paths)
+          signature_paths.flat_map do |path|
+            path = Pathname(path) unless path.is_a?(Pathname)
+            next [] unless path.directory?
+
+            Dir.glob(path.join("**", "*.rbs")).map { |p| File.expand_path(p) }
+          end.to_set
+        end
+
+        # Builds every project class (instance + singleton side) and
+        # returns the `::`-stripped names of the types whose absence
+        # raised `NoTypeFoundError`. Only the FIRST missing reference
+        # per class surfaces per build, which is why the caller loops.
+        def unresolved_referenced_types(env, project_files)
+          builder = ::RBS::DefinitionBuilder.new(env: env)
+          missing = []
+          env.class_decls.each do |type_name, entry|
+            next unless project_entry?(entry, project_files)
+
+            %i[build_instance build_singleton].each do |build|
+              builder.public_send(build, type_name)
+            rescue ::RBS::NoTypeFoundError => e
+              name = e.message[/Could not find (\S+)/, 1]
+              missing << name.sub(/\A::/, "") if name
+            rescue ::RBS::BaseError
+              # Other build failures (duplicate decl, mixin cycle, ...)
+              # are not ours to repair here — leave them fail-soft.
+            end
+          end
+          missing.uniq
+        end
+
+        # True when a `class_decls` entry was declared in one of the
+        # project's own signature files (by declaration location), so
+        # the sweep skips the bundled stdlib / vendored universe.
+        def project_entry?(entry, project_files)
+          decl = entry.respond_to?(:primary_decl) ? entry.primary_decl : nil
+          location = decl&.location
+          buffer_name = location&.buffer&.name
+          return false unless buffer_name
+
+          project_files.include?(File.expand_path(buffer_name.to_s))
+        end
+
+        # Adds empty stub declarations for the missing referenced types
+        # (and any enclosing namespace they need) to the pre-resolve
+        # env, tagged with {SYNTHETIC_STUB_BUFFER}. A name that is a
+        # prefix of another name is declared `module` (it is a
+        # namespace); a leaf is declared `class` (referenced types
+        # appear in instance position far more often than as mixins).
+        def append_stub_declarations(base_env, missing)
+          names = missing.to_set
+          missing.each do |name|
+            parts = name.split("::")
+            (1...parts.length).each { |i| names << parts[0, i].join("::") }
+          end
+          source = names.sort_by { |n| n.count(":") }.map do |name|
+            keyword = names.any? { |other| other != name && other.start_with?("#{name}::") } ? "module" : "class"
+            "#{keyword} #{name}\nend\n"
+          end.join
+          buffer = ::RBS::Buffer.new(name: SYNTHETIC_STUB_BUFFER, content: source)
+          _, directives, decls = ::RBS::Parser.parse_signature(buffer)
+          base_env.add_source(::RBS::Source::RBS.new(buffer, directives || [], decls || []))
+        rescue ::RBS::BaseError
+          nil
         end
 
         # ADR-32 WD4 — merge synthesised-from-source RBS strings
@@ -192,6 +375,40 @@ module Rigor
         @hierarchy = RbsHierarchy.new(self)
       end
 
+      # The enclosing namespaces {.synthesize_missing_namespaces} had to
+      # invent because the project's `signature_paths:` RBS declared
+      # qualified names (`class Foo::Bar`) without ever declaring `Foo`.
+      # Recovered by scanning the built env for class/module entries
+      # whose every declaration originated from the synthetic buffer, so
+      # the answer survives the marshalled-env cache (where no build-time
+      # collector would). Returns `::`-stripped names, shallowest-first.
+      # Empty for a well-formed sig set (the common case) and whenever
+      # the env failed to build.
+      def synthesized_namespaces
+        names_synthesized_in(SYNTHETIC_NAMESPACE_BUFFER)
+      end
+
+      # The referenced-but-undeclared types
+      # {.stub_missing_referenced_types} stubbed so the project classes
+      # that mention them could build (e.g. an unavailable
+      # `DRb::DRbServer`, or a stale `Textbringer::EditorError`).
+      # Recovered off the built env like {#synthesized_namespaces}, so
+      # it survives the marshalled-env cache.
+      def synthesized_stub_types
+        names_synthesized_in(SYNTHETIC_STUB_BUFFER)
+      end
+
+      # Every type name Rigor invented to make an otherwise-inert /
+      # unbuildable project signature set resolve — both the namespace
+      # stubs and the referenced-type stubs. {MethodDispatcher} resolves
+      # a call whose receiver is one of these (and that no real
+      # signature answered) to `Dynamic[Top]`, so the empty stub never
+      # mis-fires `call.undefined-method`. Memoised; empty (and cheap)
+      # for the common well-formed sig set.
+      def synthesized_type_names
+        @state[:synthesized_type_names] ||= (synthesized_namespaces + synthesized_stub_types).to_set
+      end
+
       # Returns true when an RBS class or module declaration with the given
       # name is loaded. Accepts unprefixed or top-level-prefixed names
       # ("Integer" or "::Integer"). Memoized per-name (positive and
@@ -284,6 +501,27 @@ module Rigor
         # registry rather than crashing.
       end
 
+      # Like {#each_class_decl_annotation}, but also yields the
+      # owning class / module's RBS name as the first block
+      # argument: `(class_name, annotation_string, location)`. Used
+      # by {Rigor::RbsExtended::ConformanceChecker} to resolve a
+      # `rigor:v1:conforms-to` directive back to the class it
+      # annotates. Same fail-soft policy as the un-named variant.
+      def each_class_decl_annotation_with_name
+        return enum_for(:each_class_decl_annotation_with_name) unless block_given?
+        return if env.nil?
+
+        env.class_decls.each do |rbs_name, entry|
+          entry.each_decl do |decl|
+            next unless decl.respond_to?(:annotations)
+
+            decl.annotations.each { |a| yield rbs_name.to_s, a.string, a.location }
+          end
+        end
+      rescue ::RBS::BaseError, ::Ractor::IsolationError
+        # fail-soft: see #each_class_decl_annotation.
+      end
+
       # Returns a frozen `Hash<String, String>` mapping each loaded
       # class / module name (top-level prefixed) to the file path of
       # its FIRST declaration's RBS source. Used by
@@ -354,6 +592,44 @@ module Rigor
         definition.methods[method_name.to_sym]
       end
 
+      # @return [Array<Symbol>, nil] every instance-method name on
+      #   `class_name` — own, inherited, and included — as resolved
+      #   by `RBS::DefinitionBuilder`. Returns `nil` (NOT `[]`) when
+      #   the class definition cannot be built so callers can tell
+      #   "no methods" apart from "unknown class". Used by the
+      #   `rigor:v1:conforms-to` presence check
+      #   ({Rigor::RbsExtended::ConformanceChecker}).
+      def instance_method_names(class_name)
+        definition = instance_definition(class_name)
+        return nil unless definition
+
+        definition.methods.keys
+      end
+
+      # @return [RBS::Definition, nil] the built definition for the RBS
+      #   interface `interface_name` (`_RewindableStream`), whose `.methods`
+      #   are the required members (including interface-ancestor members).
+      #   Returns `nil` when the name does not resolve to a loaded interface
+      #   (a typo, or the defining library / sig set is not on the load
+      #   path). Fail-soft on RBS build errors.
+      def interface_definition(interface_name)
+        rbs_name = parse_type_name(interface_name)
+        return nil unless rbs_name
+        return nil if env.nil?
+        return nil unless env.interface_decls.key?(rbs_name)
+
+        builder.build_interface(rbs_name)
+      rescue ::RBS::BaseError
+        nil
+      end
+
+      # @return [Array<Symbol>, nil] every method name required by the RBS
+      #   interface `interface_name`, or nil when it does not resolve. Thin
+      #   accessor over {#interface_definition} for the presence check.
+      def interface_method_names(interface_name)
+        interface_definition(interface_name)&.methods&.keys
+      end
+
       # @return [RBS::Definition, nil] the resolved singleton (class
       #   object) definition for `class_name`. The methods on this
       #   definition are the *class methods* of `class_name`, including
@@ -546,6 +822,47 @@ module Rigor
 
       private
 
+      # The `::`-stripped names of every class/module entry whose
+      # declarations ALL originated from the given sentinel buffer —
+      # i.e. names Rigor synthesized, not names the project declared.
+      # Reads off the built env so the answer survives the marshalled
+      # env cache; shallowest-first. Empty when the env failed to build.
+      def names_synthesized_in(buffer_name)
+        e = env
+        return [] if e.nil?
+
+        names = e.class_decls.filter_map do |type_name, entry|
+          decls = entry_declarations(entry)
+          next if decls.empty?
+          next unless decls.all? { |decl| synthetic_decl?(decl, buffer_name) }
+
+          type_name.to_s.sub(/\A::/, "")
+        end
+        names.sort_by { |name| name.count("::") }
+      end
+
+      # Collects the AST declaration nodes behind a `class_decls`
+      # entry. RBS 4's `ModuleEntry` / `ClassEntry` expose `each_decl`;
+      # the older single-`decl` shape is handled defensively so the
+      # loader survives an rbs-gem minor bump.
+      def entry_declarations(entry)
+        if entry.respond_to?(:each_decl)
+          [].tap { |acc| entry.each_decl { |decl| acc << decl } }
+        elsif entry.respond_to?(:decl)
+          [entry.decl]
+        else
+          []
+        end
+      end
+
+      # True when an AST declaration was emitted into `buffer_name`
+      # (one of the synthetic-source sentinels) — identified by the
+      # buffer name on its location.
+      def synthetic_decl?(decl, buffer_name)
+        location = decl.respond_to?(:location) ? decl.location : nil
+        location&.buffer&.name.to_s == buffer_name
+      end
+
       def constant_type_table
         @constant_type_table ||= begin
           require_relative "../cache/rbs_constant_table"
@@ -725,14 +1042,28 @@ module Rigor
         nil
       end
 
+      # Memoised on `@state` (the per-loader store also holding `:env` /
+      # `:builder`): `RBS::TypeName.parse` is a pure, deterministic
+      # function of the normalised string, and the `RBS::TypeName` it
+      # returns is a frozen value object safe to share across callers
+      # (every consumer only reads it — `env.class_decls.key?` /
+      # `builder.build_*`). The same handful of class names are parsed
+      # on nearly every call-site dispatch, so this was a top allocation
+      # site; caching the immutable result (nil included) removes it.
       def parse_type_name(name)
         s = name.to_s
         return nil if s.empty?
 
         s = "::#{s}" unless s.start_with?("::")
-        RBS::TypeName.parse(s)
-      rescue ::RBS::BaseError
-        nil
+        cache = (@state[:type_name_cache] ||= {})
+        return cache[s] if cache.key?(s)
+
+        cache[s] =
+          begin
+            RBS::TypeName.parse(s)
+          rescue ::RBS::BaseError
+            nil
+          end
       end
 
       def compute_class_known(name)

data/lib/rigor/environment.rb

@@ -512,8 +512,14 @@ module Rigor
     # presence check without materialising a type carrier.
     def class_known?(name)
       return true if class_registry.nominal_for_name(name)
-
-      class_known_in_rbs?(name)
+      return true if class_known_in_rbs?(name)
+
+      # ADR-36 nested-class emission — a variant subclass the
+      # substrate synthesised (e.g. `Shape::Circle` from a
+      # `variants do variant Circle, Float end` block) is a real
+      # class for resolution purposes even though no RBS / source
+      # declares it.
+      @synthetic_method_index&.knows_class?(name) || false
     end
 
     # ADR-15 Phase 2b — returns the loader's read-only,

data/lib/rigor/inference/block_parameter_binder.rb

@@ -174,8 +174,7 @@ module Rigor
 
       def bind_trailing_positionals(params_node, bindings, cursor)
         params_node.posts.each do |param|
-          name = required_name(param)
-          bindings[name] = positional_type_at(cursor) if name
+          bind_required_param(param, cursor, bindings)
           cursor += 1
         end
         cursor

data/lib/rigor/inference/budget_trace.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # Opt-in counters for the hard-coded inference cutoffs — the
+    # "budget" guards that silently return `Dynamic[top]` / `nil` /
+    # a fallback bound rather than emitting a diagnostic. These are
+    # the *operative* cutoffs in the engine today (the configurable
+    # `budgets:` table in docs/type-specification/inference-budgets.md
+    # is not yet wired); counting how often each fires on a real
+    # project is the only way to see where inference actually stops.
+    #
+    # Three categories, one per guard site:
+    #
+    # - {RECURSION_GUARD} — `ExpressionTyper#infer_user_method_return`
+    #   detected a `(receiver, method)` cycle and returned
+    #   `Dynamic[top]` (the de-facto recursion-depth budget, effective
+    #   depth 1).
+    # - {ANCESTOR_WALK_LIMIT} — `resolve_user_def_through_ancestors`
+    #   hit the 100-node BFS cap and gave up resolving the self-call.
+    # - {HKT_FUEL_EXHAUSTED} — `HktReducer` ran out of its reduction
+    #   fuel budget and unwound to `app.bound`.
+    #
+    # Enabled only when `RIGOR_BUDGET_TRACE` is set (to any non-empty
+    # value) in the environment, or via {enable!} in tests. When
+    # disabled, {hit} is a single boolean check and returns
+    # immediately, so normal runs pay nothing.
+    #
+    # Counters are process-global (Mutex-guarded) so they aggregate
+    # across threads, but they do NOT cross `fork` boundaries — run
+    # `rigor check --workers 0` to keep all inference in one process
+    # when collecting a trace.
+    module BudgetTrace
+      RECURSION_GUARD = :recursion_guard
+      ANCESTOR_WALK_LIMIT = :ancestor_walk_limit
+      HKT_FUEL_EXHAUSTED = :hkt_fuel_exhausted
+
+      CATEGORIES = [RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED].freeze
+
+      # Distribution (histogram) categories — read-only observations of
+      # a value's size at a site, used to choose budget defaults from an
+      # observed tail rather than a guess (ADR-41 WD3 / Slice 2a). No cap
+      # is enforced; these only record. `UNION_ARITY` is the member count
+      # of every `Type::Union` that `Combinator.union` produces — the
+      # distribution the `union_size` budget default should be set from.
+      UNION_ARITY = :union_arity
+
+      DISTRIBUTION_CATEGORIES = [UNION_ARITY].freeze
+
+      @enabled = !ENV["RIGOR_BUDGET_TRACE"].to_s.empty?
+      @mutex = Mutex.new
+      @counts = Hash.new(0)
+      @distributions = Hash.new { |h, k| h[k] = Hash.new(0) }
+
+      module_function
+
+      def enabled?
+        @enabled
+      end
+
+      # Test / programmatic toggles. Production enablement is the
+      # `RIGOR_BUDGET_TRACE` env var read once at load time.
+      def enable!
+        @enabled = true
+      end
+
+      def disable!
+        @enabled = false
+      end
+
+      # Records one firing of `category`. No-op (one boolean check)
+      # when tracing is disabled.
+      def hit(category)
+        return unless @enabled
+
+        @mutex.synchronize { @counts[category] += 1 }
+      end
+
+      # Frozen snapshot of the current counts, every known category
+      # present (zero-filled) so consumers can render a stable table.
+      def snapshot
+        @mutex.synchronize do
+          CATEGORIES.to_h { |category| [category, @counts[category]] }.freeze
+        end
+      end
+
+      # Records one observation of `value` (an Integer size) into
+      # `category`'s histogram. No-op (one boolean check) when disabled.
+      def observe(category, value)
+        return unless @enabled
+
+        @mutex.synchronize { @distributions[category][value] += 1 }
+      end
+
+      # Frozen `{value => count}` histogram for a distribution category.
+      def distribution(category)
+        @mutex.synchronize { @distributions[category].dup.freeze }
+      end
+
+      # Summary of a distribution category: total observation count, max
+      # observed value, selected percentiles, and how many observations
+      # met or exceeded each threshold in `over`. Percentiles use the
+      # nearest-rank method over the expanded sample.
+      def summarize(category, over: [])
+        hist = distribution(category)
+        total = hist.values.sum
+        return { count: 0, max: 0, percentiles: {}, over: over.to_h { |t| [t, 0] } } if total.zero?
+
+        sorted = hist.keys.sort
+        { count: total,
+          max: sorted.last,
+          percentiles: { p50: percentile(hist, total, 0.50), p90: percentile(hist, total, 0.90),
+                         p99: percentile(hist, total, 0.99) },
+          over: over.to_h { |t| [t, hist.sum { |value, n| value >= t ? n : 0 }] } }
+      end
+
+      # Nearest-rank percentile over a `{value => count}` histogram
+      # without materialising the full sample.
+      def percentile(hist, total, fraction)
+        rank = (fraction * total).ceil
+        cumulative = 0
+        hist.keys.sort.each do |value|
+          cumulative += hist[value]
+          return value if cumulative >= rank
+        end
+        hist.keys.max
+      end
+
+      def reset
+        @mutex.synchronize do
+          @counts.clear
+          @distributions.clear
+        end
+      end
+    end
+  end
+end

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

@@ -13,11 +13,8 @@ module Rigor
       # `ary_push_internal`, …) that the classifier does not yet
       # recognise. The blocklist captures the methods we have
       # specifically observed flowing as `:leaf` despite mutating.
-      ARRAY_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/array.yml",
-          __dir__
-        ),
+      ARRAY_CATALOG = MethodCatalog.for_topic(
+        "array",
         mutating_selectors: {
           "Array" => Set[
             # Mutators classified `:leaf` by the C-body heuristic

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

@@ -13,11 +13,8 @@ module Rigor
       # (which dispatches on the receiver's concrete class).
       # The data is consumed by future include-aware lookup —
       # see `docs/CURRENT_WORK.md` for the planned slice.
-      COMPARABLE_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/comparable.yml",
-          __dir__
-        ),
+      COMPARABLE_CATALOG = MethodCatalog.for_topic(
+        "comparable",
         mutating_selectors: {
           "Comparable" => Set[]
         }

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

@@ -21,11 +21,8 @@ module Rigor
       # so a hypothetical future `Constant<Complex>` carrier cannot
       # fold an aliasing copy through the catalog (mirrors
       # `range_catalog.rb`, `time_catalog.rb`, `date_catalog.rb`).
-      COMPLEX_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/complex.yml",
-          __dir__
-        ),
+      COMPLEX_CATALOG = MethodCatalog.for_topic(
+        "complex",
         mutating_selectors: {
           "Complex" => Set[
             # Defence in depth: `Complex` does not currently expose

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

@@ -54,11 +54,8 @@ module Rigor
       # blocklist entry; the entries below are defense-in-depth
       # against indirect mutators the regex might miss in a future
       # CRuby bump.
-      DATE_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/date.yml",
-          __dir__
-        ),
+      DATE_CATALOG = MethodCatalog.for_topic(
+        "date",
         mutating_selectors: {
           "Date" => Set[
             # `d_lite_initialize_copy` is already classed

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

@@ -22,11 +22,8 @@ module Rigor
       # 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__
-        ),
+      ENCODING_CATALOG = MethodCatalog.for_topic(
+        "encoding",
         mutating_selectors: {
           "Encoding" => Set[
             # Defence-in-depth: mirrors range_catalog.rb /

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

@@ -13,11 +13,8 @@ module Rigor
       # (which dispatches on the receiver's concrete class).
       # The data is consumed by future include-aware lookup —
       # see `docs/CURRENT_WORK.md` for the planned slice.
-      ENUMERABLE_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/enumerable.yml",
-          __dir__
-        ),
+      ENUMERABLE_CATALOG = MethodCatalog.for_topic(
+        "enumerable",
         mutating_selectors: {
           "Enumerable" => Set[]
         }

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

@@ -26,11 +26,8 @@ module Rigor
       # 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__
-        ),
+      EXCEPTION_CATALOG = MethodCatalog.for_topic(
+        "exception",
         mutating_selectors: {
           "Exception" => Set[
             # `exc_initialize` writes `mesg` / `backtrace` ivars on

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

@@ -15,11 +15,8 @@ module Rigor
       # captures every false-positive `:leaf` we have spotted in the
       # generated YAML — bias toward conservatism so a missed fold is
       # acceptable but a folded mutator/yielder is not.
-      HASH_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/hash.yml",
-          __dir__
-        ),
+      HASH_CATALOG = MethodCatalog.for_topic(
+        "hash",
         mutating_selectors: {
           "Hash" => Set[
             # Block-dependent iteration — yields via `rb_hash_foreach`