rigortype 0.0.2 → 0.0.4

data/lib/rigor/inference/acceptance.rb

@@ -47,7 +47,18 @@ module Rigor
         if other_type.is_a?(Type::Dynamic)
           return Type::AcceptsResult.yes(mode: mode, reasons: "gradual: Dynamic[T] passes any boundary")
         end
+
+        # Structural equality short-circuit. Two identical carriers
+        # describe the same value set, so they always accept each
+        # other. This is sound for any mode and covers cases where
+        # neither side has a per-class rule for the other's exact
+        # carrier kind (the canonical example is
+        # `Intersection.accepts(Intersection)`, where the disjunction
+        # rule below would otherwise reject equal-but-narrow LHSes).
+        return Type::AcceptsResult.yes(mode: mode, reasons: "structural equality") if self_type == other_type
+
         return accepts_union_other(self_type, other_type, mode) if other_type.is_a?(Type::Union)
+        return accepts_intersection_other(self_type, other_type, mode) if other_type.is_a?(Type::Intersection)
 
         accepts_one(self_type, other_type, mode)
       end
@@ -64,6 +75,10 @@ module Rigor
         Type::Singleton => :accepts_singleton,
         Type::Nominal => :accepts_nominal,
         Type::Constant => :accepts_constant,
+        Type::IntegerRange => :accepts_integer_range,
+        Type::Difference => :accepts_difference,
+        Type::Refined => :accepts_refined,
+        Type::Intersection => :accepts_intersection,
         Type::Tuple => :accepts_tuple,
         Type::HashShape => :accepts_hash_shape
       }.freeze
@@ -126,6 +141,27 @@ module Rigor
           end
         end
 
+        # self.accepts(Intersection[Y, Z]) iff self accepts at least
+        # one Y_i. Disjunction across members because the intersection
+        # is the meet of its members' value sets, so containment in
+        # any one member implies containment of the whole
+        # intersection. Symmetric counterpart to
+        # `accepts_union_other`.
+        def accepts_intersection_other(self_type, intersection, mode)
+          results = intersection.members.map { |m| accepts(self_type, m, mode: mode) }
+
+          if results.any?(&:yes?)
+            Type::AcceptsResult.yes(mode: mode, reasons: "self accepts an intersection member")
+          elsif results.any?(&:maybe?)
+            Type::AcceptsResult.maybe(
+              mode: mode,
+              reasons: "self could not be proven to accept any intersection member"
+            )
+          else
+            Type::AcceptsResult.no(mode: mode, reasons: "self rejects every intersection member")
+          end
+        end
+
         # self.accepts(Union[Y, Z]) iff self accepts every Y_i. Strict
         # AND across members: any "no" turns the whole result no, any
         # "maybe" without a "no" gives maybe, all "yes" gives yes.
@@ -184,18 +220,40 @@ module Rigor
         # - Singleton: never (wrong value kind).
         def accepts_nominal(self_type, other_type, mode)
           case other_type
-          when Type::Nominal
-            accepts_nominal_from_nominal(self_type, other_type, mode)
-          when Type::Constant
-            accepts_nominal_from_constant(self_type, other_type, mode)
-          when Type::Singleton
-            accepts_nominal_from_singleton(self_type, other_type, mode)
+          when Type::Nominal then accepts_nominal_from_nominal(self_type, other_type, mode)
+          when Type::Constant then accepts_nominal_from_constant(self_type, other_type, mode)
+          when Type::Singleton then accepts_nominal_from_singleton(self_type, other_type, mode)
+          when Type::IntegerRange then accepts_nominal_from_integer_range(self_type, other_type, mode)
+          else accepts_nominal_from_shape(self_type, other_type, mode)
+          end
+        end
+
+        # Tail of `accepts_nominal` that handles structural shape
+        # carriers (`Tuple` / `HashShape`) and refinement carriers
+        # (`Difference` / `Refined`). Each branch projects the
+        # other-side carrier to the nominal layer it sits above
+        # and re-runs acceptance — soundness follows because the
+        # carrier's value set is contained in the projected
+        # nominal's value set.
+        def accepts_nominal_from_shape(self_type, other_type, mode)
+          case other_type
           when Type::Tuple
             accepts(self_type, project_tuple_to_nominal(other_type), mode: mode)
               .with_reason("projected Tuple to Nominal[Array]")
           when Type::HashShape
             accepts(self_type, project_hash_shape_to_nominal(other_type), mode: mode)
               .with_reason("projected HashShape to Nominal[Hash]")
+          when Type::Difference, Type::Refined
+            # A refinement carrier's value set is a subset of its
+            # base. So if `self` (Nominal) accepts the base, it
+            # also accepts the refinement; if it rejects the
+            # base, it cannot accept any subset of it. Forward
+            # through to the base nominal so the standard subtype
+            # check applies. The recursion is bounded because
+            # every refinement carrier's `base` is closer to the
+            # nominal layer.
+            accepts(self_type, other_type.base, mode: mode)
+              .with_reason("projected #{other_type.class.name.split('::').last} to its base")
           else
             Type::AcceptsResult.no(
               mode: mode,
@@ -204,6 +262,33 @@ module Rigor
           end
         end
 
+        # `Nominal[Integer]` (and anything Integer is-a, like Numeric) accepts
+        # any `IntegerRange`; nothing else does. Argument-bearing `Nominal`s
+        # never accept `IntegerRange` because IntegerRange has no type args.
+        INTEGER_NOMINAL_ANCESTORS = %w[Integer Numeric Comparable Object BasicObject].freeze
+        private_constant :INTEGER_NOMINAL_ANCESTORS
+
+        def accepts_nominal_from_integer_range(self_type, _other_type, mode)
+          unless self_type.type_args.empty?
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Nominal[#{self_type.class_name}] with type args rejects IntegerRange"
+            )
+          end
+
+          if INTEGER_NOMINAL_ANCESTORS.include?(self_type.class_name)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "IntegerRange is-a #{self_type.class_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Nominal[#{self_type.class_name}] rejects IntegerRange"
+            )
+          end
+        end
+
         # v0.0.2 — meta-type rule. A `Singleton[T]` is the
         # class object for `T`, so it is an instance of
         # `Class` (when `T` is a class) and always an instance
@@ -344,6 +429,239 @@ module Rigor
           end
         end
 
+        # IntegerRange[a..b] accepts:
+        # - Constant[n] where n is an Integer covered by [a..b];
+        # - IntegerRange[c..d] where [c..d] ⊆ [a..b];
+        # - Nominal[Integer] only when self is the universal range
+        #   (`int<min, max>`), since otherwise an arbitrary Integer
+        #   could fall outside the bound.
+        # Anything else is rejected.
+        def accepts_integer_range(self_type, other_type, mode)
+          case other_type
+          when Type::Constant
+            accepts_integer_range_from_constant(self_type, other_type, mode)
+          when Type::IntegerRange
+            accepts_integer_range_from_integer_range(self_type, other_type, mode)
+          when Type::Nominal
+            accepts_integer_range_from_nominal(self_type, other_type, mode)
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "IntegerRange rejects #{other_type.class}"
+            )
+          end
+        end
+
+        def accepts_integer_range_from_constant(self_type, constant, mode)
+          unless constant.value.is_a?(Integer)
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "IntegerRange rejects non-Integer Constant"
+            )
+          end
+
+          if self_type.covers?(constant.value)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "Constant[#{constant.value}] is in #{self_type.describe}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Constant[#{constant.value}] outside #{self_type.describe}"
+            )
+          end
+        end
+
+        def accepts_integer_range_from_integer_range(self_type, other_range, mode)
+          if self_type.lower <= other_range.lower && other_range.upper <= self_type.upper
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "#{other_range.describe} ⊆ #{self_type.describe}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{other_range.describe} not contained in #{self_type.describe}"
+            )
+          end
+        end
+
+        def accepts_integer_range_from_nominal(self_type, nominal, mode)
+          unless nominal.class_name == "Integer"
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "IntegerRange rejects Nominal[#{nominal.class_name}]"
+            )
+          end
+
+          if self_type.universal?
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "universal IntegerRange accepts Nominal[Integer]"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "non-universal IntegerRange rejects Nominal[Integer] (could fall outside #{self_type.describe})"
+            )
+          end
+        end
+
+        # `Difference[base, removed]` accepts another type X when
+        # the base accepts X *and* X's value set is provably
+        # disjoint from `removed`. The disjointness test is the
+        # subtle part — it is NOT the same as `removed.accepts(X)`,
+        # because `Nominal[String]` includes `""` even though
+        # `Constant[""]` does not "accept" `Nominal[String]`.
+        # The conservative rule here: we can prove disjointness
+        # only when X is itself a `Constant` carrier (compare
+        # values directly) or another `Difference` with the same
+        # removed value (already exhibits the disjointness). Any
+        # other shape — Nominal, Union, IntegerRange — could
+        # overlap the removed value, so the difference rejects
+        # it under gradual mode.
+        def accepts_difference(self_type, other_type, mode)
+          base_result = accepts(self_type.base, other_type, mode: mode)
+          return base_result if base_result.no?
+
+          unless provably_disjoint_from_removed?(other_type, self_type.removed)
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{self_type.describe} cannot prove #{other_type.class} excludes the removed value"
+            )
+          end
+
+          base_result.with_reason("#{self_type.describe}: base accepts and removed is disjoint")
+        end
+
+        def provably_disjoint_from_removed?(other_type, removed)
+          case other_type
+          when Type::Constant
+            !(removed.is_a?(Type::Constant) && removed.value == other_type.value)
+          when Type::Difference
+            # `Difference[A, R].accepts(Difference[B, R])`: the
+            # other carrier already excludes `R` at its difference
+            # layer, so the disjointness is exhibited regardless of
+            # how `B` (its base) relates to `R`. We do NOT recurse
+            # into `other_type.base` because that would always fail
+            # (a Nominal base contains the removed value).
+            other_type.removed == removed
+          when Type::Intersection
+            # Disjointness is monotonic over Intersection: if any
+            # member is provably disjoint from `removed`, the meet
+            # is too.
+            other_type.members.any? { |m| provably_disjoint_from_removed?(m, removed) }
+          end
+        end
+
+        # `Refined[base, predicate]` accepts another type X when
+        # the base accepts the *base* of X *and* X is provably
+        # contained in the predicate's value set. The base
+        # check is delegated to `accepts(self.base, X.base)`
+        # so handlers like `accepts_nominal` see Nominal-vs-
+        # Nominal and return their normal answer (the inner
+        # `accepts_nominal` does not register `Refined` /
+        # `Difference` as direct other-shapes — projecting to
+        # the base is what makes the comparison meaningful).
+        #
+        # Provability rules in gradual mode (the conservative
+        # analogue of `accepts_difference`):
+        #
+        # - X is a `Refined` with the *same* predicate_id —
+        #   exact predicate match, accept.
+        # - X is a `Constant` whose value the predicate's
+        #   recogniser accepts — the value is statically
+        #   contained, accept. A recognised non-match is `:no`.
+        # - Anything else (Nominal, Union, IntegerRange,
+        #   Difference) — predicate-subset cannot be proven
+        #   without a runtime test, so reject under gradual
+        #   mode rather than degrade to `:maybe`. Mirrors the
+        #   `accepts_difference` policy.
+        def accepts_refined(self_type, other_type, mode)
+          case other_type
+          when Type::Refined then accepts_refined_from_refined(self_type, other_type, mode)
+          when Type::Constant then accepts_refined_from_constant(self_type, other_type, mode)
+          else accepts_refined_other_shape(self_type, other_type, mode)
+          end
+        end
+
+        def accepts_refined_from_refined(self_type, other_type, mode)
+          base_result = accepts(self_type.base, other_type.base, mode: mode)
+          return base_result if base_result.no?
+
+          if other_type.predicate_id == self_type.predicate_id
+            base_result.with_reason("matching predicate :#{self_type.predicate_id}")
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "predicate mismatch: :#{self_type.predicate_id} vs :#{other_type.predicate_id}"
+            )
+          end
+        end
+
+        def accepts_refined_from_constant(self_type, constant, mode)
+          base_result = accepts(self_type.base, constant, mode: mode)
+          return base_result if base_result.no?
+
+          case self_type.matches?(constant.value)
+          when true
+            base_result.with_reason("Constant value satisfies :#{self_type.predicate_id}")
+          when false
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Constant value fails :#{self_type.predicate_id}"
+            )
+          else
+            Type::AcceptsResult.maybe(
+              mode: mode,
+              reasons: "predicate :#{self_type.predicate_id} not in registry"
+            )
+          end
+        end
+
+        def accepts_refined_other_shape(self_type, other_type, mode)
+          base_result = accepts(self_type.base, other_type, mode: mode)
+          return base_result if base_result.no?
+
+          Type::AcceptsResult.no(
+            mode: mode,
+            reasons: "#{self_type.describe} cannot prove #{other_type.class} satisfies " \
+                     ":#{self_type.predicate_id}"
+          )
+        end
+
+        # `Intersection[M1, M2, …]` accepts X iff *every* member
+        # accepts X — the meet of value sets is contained iff the
+        # candidate is contained in each. Conjunctive combine: any
+        # `:no` makes the result `:no`, any `:maybe` without a
+        # `:no` makes the result `:maybe`, all `:yes` makes the
+        # result `:yes`. The 0-member case is unreachable because
+        # `Combinator.intersection` collapses empty intersections
+        # to `Top`.
+        def accepts_intersection(self_type, other_type, mode)
+          per_member = self_type.members.map { |m| accepts(m, other_type, mode: mode) }
+
+          if per_member.any?(&:no?)
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "an intersection member rejected #{other_type.class}"
+            )
+          end
+
+          if per_member.any?(&:maybe?)
+            Type::AcceptsResult.maybe(
+              mode: mode,
+              reasons: "an intersection member could not be proven accepted"
+            )
+          else
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "every intersection member accepted #{other_type.class}"
+            )
+          end
+        end
+
         # Constant[v] accepts only Constant[v'] with structurally equal
         # value. Any other type is rejected (modulo the universal
         # Bot/Dynamic short-circuits already applied upstream).

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Array` catalog. Singleton — load once, consult during dispatch.
+      #
+      # Array has more mutation surface than String: every method that
+      # logically reshapes the array tends to call `rb_ary_modify` or
+      # an internal helper (`ary_replace`, `ary_resize`, `ary_pop`,
+      # `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__
+        ),
+        mutating_selectors: {
+          "Array" => Set[
+            # Mutators classified `:leaf` by the C-body heuristic
+            :<<, :push, :replace, :clear, :concat, :insert, :"[]=",
+            :unshift, :prepend, :pop, :shift, :delete_at, :slice!,
+            :compact!, :flatten!, :uniq!, :sort!, :reverse!,
+            :rotate!, :keep_if, :delete_if, :select!, :filter!,
+            :reject!, :collect!, :map!, :assoc, :rassoc,
+            :fill, :delete, :transpose,
+            # Methods that yield (block-dependent) — classifier
+            # may mark them leaf when the block call is gated:
+            :each, :each_with_index, :each_index, :each_slice,
+            :each_cons, :each_with_object,
+            # Identity/comparison methods that take a block too
+            :max, :min, :max_by, :min_by, :minmax, :minmax_by,
+            :sort_by, :group_by, :partition, :all?, :any?, :none?,
+            :one?, :find, :detect, :find_all, :find_index,
+            :reduce, :inject, :flat_map, :collect_concat,
+            :zip, :product, :combination, :permutation,
+            :chunk_while, :slice_when, :tally
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Hash` catalog. Singleton — load once, consult during dispatch.
+      #
+      # Hash mirrors Array's mutation pattern: nearly every iteration
+      # method yields through `rb_hash_foreach` plus a per-pair static
+      # callback (`each_value_i`, `keep_if_i`, …), and the C-body
+      # classifier does not follow into the callback so it lands as
+      # `:leaf` despite being block-dependent. The blocklist below
+      # 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__
+        ),
+        mutating_selectors: {
+          "Hash" => Set[
+            # Block-dependent iteration — yields via `rb_hash_foreach`
+            # plus a per-pair callback that the regex classifier does
+            # not follow:
+            :each, :each_pair, :each_key, :each_value,
+            :select, :filter, :reject,
+            :transform_values,
+            # Block-dependent merge — `rb_hash_merge` delegates into
+            # `rb_hash_update`, which yields per conflict when a block
+            # is given:
+            :merge
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  module Inference
+    module Builtins
+      # Generic loader for offline-generated catalogs under
+      # `data/builtins/ruby_core/<topic>.yml`. One instance per topic
+      # (numeric, string, array, …); each owns the path to its own
+      # YAML and the per-class blocklist of selectors the static
+      # classifier marked `:leaf` but that actually mutate the
+      # receiver (false positives the C-body heuristic does not
+      # catch).
+      #
+      # `safe_for_folding?(class_name, selector, kind:)` returns true
+      # when:
+      # 1. The catalog has an entry for `(class_name, selector, kind)`,
+      # 2. The entry's `purity` is one of `leaf` / `trivial` /
+      #    `leaf_when_numeric`,
+      # 3. The selector is NOT in the per-class mutation blocklist.
+      #
+      # Missing catalog files (e.g. in a bare gem install where data
+      # was opted out) degrade to `false` so the dispatcher falls
+      # back to its hand-rolled allow lists.
+      class MethodCatalog
+        FOLDABLE_PURITIES = Set["leaf", "trivial", "leaf_when_numeric"].freeze
+        EMPTY_CATALOG = { "classes" => {} }.freeze
+
+        def initialize(path:, mutating_selectors: {})
+          @path = path
+          @mutating_selectors = mutating_selectors.transform_values(&:freeze).freeze
+          @catalog = nil
+        end
+
+        def safe_for_folding?(class_name, selector, kind: :instance)
+          class_name_str = class_name.to_s
+          return false if blocked?(class_name_str, selector)
+
+          entry = method_entry(class_name_str, selector, kind: kind)
+          return false unless entry
+
+          FOLDABLE_PURITIES.include?(entry["purity"])
+        end
+
+        def method_entry(class_name, selector, kind: :instance)
+          klass = catalog.dig("classes", class_name.to_s)
+          return nil unless klass
+
+          bucket_key = kind == :singleton ? "singleton_methods" : "instance_methods"
+          klass.dig(bucket_key, selector.to_s)
+        end
+
+        def reset!
+          @catalog = nil
+        end
+
+        private
+
+        def blocked?(class_name, selector)
+          # Bang-suffixed selectors are mutating by Ruby convention
+          # (`upcase!`, `concat`, etc. are listed explicitly below;
+          # this catches the rest). We bias toward false negatives:
+          # losing a fold opportunity is acceptable; folding a
+          # mutator is not.
+          selector_str = selector.to_s
+          return true if selector_str.end_with?("!")
+
+          per_class = @mutating_selectors[class_name]
+          return false if per_class.nil?
+
+          per_class.include?(selector.to_sym) || per_class.include?(selector_str.to_sym)
+        end
+
+        def catalog
+          @catalog ||= load_catalog
+        end
+
+        def load_catalog
+          return EMPTY_CATALOG unless File.exist?(@path)
+
+          data = YAML.safe_load_file(@path, permitted_classes: [Symbol])
+          data.is_a?(Hash) ? data : EMPTY_CATALOG
+        rescue Psych::SyntaxError
+          EMPTY_CATALOG
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  module Inference
+    module Builtins
+      # Read-only loader for the Numeric/Integer/Float built-in method
+      # catalog at `data/builtins/ruby_core/numeric.yml`. The catalog is
+      # produced offline by `tool/extract_numeric_catalog.rb` from the
+      # CRuby reference checkout under `references/ruby` plus the RBS
+      # core signatures under `references/rbs`.
+      #
+      # The loader is the runtime bridge: callers ask "is `Integer#+`
+      # safe to invoke during constant folding?" and the answer comes
+      # straight from the offline classification (`leaf`, `trivial`,
+      # `leaf_when_numeric` are foldable; everything else is not).
+      #
+      # The catalog is loaded lazily on first access and memoised for
+      # the lifetime of the process. If the file is missing (e.g. in a
+      # bare gem install where the consumer opted out of shipping data
+      # files, or in a development checkout that has not yet generated
+      # the catalog) the loader degrades to an empty catalog so calls
+      # uniformly return `false` and the rest of the dispatcher
+      # continues with its hand-rolled allow lists.
+      module NumericCatalog
+        # Purity tags from the catalog that are safe for the analyzer
+        # to invoke against concrete literal receivers/arguments.
+        # `leaf_when_numeric` is included because `ConstantFolding`
+        # only lets it through when every argument is itself a
+        # `Constant<Numeric>` or `IntegerRange` — exactly the gate
+        # the catalog tag is named for.
+        FOLDABLE_PURITIES = Set["leaf", "trivial", "leaf_when_numeric"].freeze
+
+        EMPTY_CATALOG = { "classes" => {} }.freeze
+        private_constant :EMPTY_CATALOG
+
+        # Path resolved relative to this file. The catalog ships under
+        # `data/builtins/ruby_core/numeric.yml` at the gem root.
+        CATALOG_PATH = File.expand_path(
+          "../../../../data/builtins/ruby_core/numeric.yml",
+          __dir__
+        )
+        private_constant :CATALOG_PATH
+
+        class << self
+          # @param class_name [String] e.g. "Integer", "Float"
+          # @param selector [Symbol, String]
+          # @param kind [Symbol] :instance (default) or :singleton
+          # @return [Boolean]
+          def safe_for_folding?(class_name, selector, kind: :instance)
+            entry = method_entry(class_name, selector, kind: kind)
+            return false unless entry
+
+            FOLDABLE_PURITIES.include?(entry["purity"])
+          end
+
+          # @return [Hash, nil] catalog entry for the given method, or
+          #   nil when the method is not registered.
+          def method_entry(class_name, selector, kind: :instance)
+            klass = catalog.dig("classes", class_name.to_s)
+            return nil unless klass
+
+            bucket_key = kind == :singleton ? "singleton_methods" : "instance_methods"
+            klass.dig(bucket_key, selector.to_s)
+          end
+
+          # Used by tests to drop the cached catalog so a different
+          # path or content can be exercised. Production code MUST
+          # NOT call this during normal operation.
+          def reset!
+            @catalog = nil
+          end
+
+          private
+
+          def catalog
+            @catalog ||= load_catalog
+          end
+
+          def load_catalog
+            return EMPTY_CATALOG unless File.exist?(CATALOG_PATH)
+
+            data = YAML.safe_load_file(CATALOG_PATH, permitted_classes: [Symbol])
+            data.is_a?(Hash) ? data : EMPTY_CATALOG
+          rescue Psych::SyntaxError
+            EMPTY_CATALOG
+          end
+        end
+      end
+    end
+  end
+end