rigortype 0.1.18 → 0.1.19

data/lib/rigor/cli/annotate_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "English"
 require "optionparser"
 require "prism"
 
@@ -8,6 +9,7 @@ require_relative "../environment"
 require_relative "../scope"
 require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
+require_relative "../inference/statement_evaluator"
 require_relative "prism_colorizer"
 require_relative "command"
 
@@ -20,18 +22,33 @@ module Rigor
     # (so `1; 2; 3` reports `3`), or, for a line that no statement
     # closes, the widest expression ending there (so the `if nil`
     # header reports its condition). It infers that expression's
-    # type and appends a `#=> dump_type: <type>` comment.
+    # type and appends a `#=> <type>` comment (the xmpfilter /
+    # seeing_is_believing convention).
     #
     # The annotated source is re-parsed with Prism — a sanity gate,
     # since the appended text is always a comment — and printed to
-    # stdout with IRB-style syntax highlighting via
+    # stdout. When colour is enabled and `bat`
+    # (https://github.com/sharkdp/bat) is on PATH it is used for
+    # highlighting; otherwise IRB-style highlighting via
     # {PrismColorizer}.
     class AnnotateCommand < Command
       USAGE = "Usage: rigor annotate [options] FILE"
 
-      # Appended ` #=> dump_type: <type>` suffix. Matched and
-      # stripped before re-annotating so re-running is idempotent.
-      ANNOTATION_PATTERN = /\s*#=>\s*dump_type:.*\z/
+      # Trailing `#=> …` annotation comment. Matched and stripped
+      # before re-annotating so re-running is idempotent — this
+      # follows xmpfilter's convention of owning the `#=>` marker,
+      # and also absorbs the pre-v0.2.0 `#=> dump_type: <type>`
+      # spelling. The leading `\s` requirement keeps a `#=>` inside
+      # a string literal (no preceding whitespace ambiguity aside)
+      # from matching mid-expression.
+      ANNOTATION_PATTERN = /\s+#=>(?:\s.*)?\z/
+
+      # Arguments for highlighting through `bat`: the annotated
+      # text arrives on stdin, so the language must be explicit;
+      # `--style=plain` drops the grid/header chrome so the output
+      # matches the PrismColorizer fallback line-for-line; paging
+      # stays off because the CLI may itself sit in a pipeline.
+      BAT_ARGS = %w[--language=ruby --style=plain --paging=never --color=always].freeze
 
       # @return [Integer] CLI exit status.
       def run
@@ -54,7 +71,7 @@ module Rigor
       def parse_options
         # Default: colour a tty, unless `NO_COLOR` opts out. An
         # explicit `--color` / `--no-color` overrides both.
-        options = { config: nil, color: @out.tty? && !no_color_env? }
+        options = { config: nil, color: @out.tty? && !no_color_env?, bat: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
@@ -63,6 +80,10 @@ module Rigor
                   "Force or disable ANSI colour (default: auto-detect a tty; honours NO_COLOR)") do |value|
             options[:color] = value
           end
+          opts.on("--[no-]bat",
+                  "Force or disable highlighting through bat (default: when colour is on and bat is found)") do |value|
+            options[:bat] = value
+          end
         end
         parser.parse!(@argv)
 
@@ -91,12 +112,17 @@ module Rigor
         parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
         return 1 if parse_errors?(parse_result, file)
 
+        # `converged_loop_recording` re-records fixpoint-tracked loop
+        # bodies from their converged (post-writeback) bindings, so a
+        # loop-body line annotates the joined widened type (`Integer`)
+        # rather than a stale first-iterations constant (`1 | 2`).
         scope_index = Inference::ScopeIndexer.index(
-          parse_result.value, default_scope: base_scope(configuration)
+          parse_result.value, default_scope: base_scope(configuration),
+                              converged_loop_recording: true
         )
         line_types = LineTypeCollector.new(scope_index).collect(parse_result.value)
 
-        @out.puts(render(annotate(source, line_types), color: options.fetch(:color)))
+        @out.puts(render(annotate(source, line_types), color: options.fetch(:color), bat: options.fetch(:bat)))
         0
       end
 
@@ -118,8 +144,8 @@ module Rigor
         true
       end
 
-      # Appends ` #=> dump_type: <type>` to every line a type was
-      # inferred for, aligning the comment column.
+      # Appends ` #=> <type>` to every line a type was inferred
+      # for, aligning the comment column.
       def annotate(source, line_types)
         lines = source.lines
         column = annotation_column(lines, line_types)
@@ -130,7 +156,7 @@ module Rigor
           code = line.chomp.sub(ANNOTATION_PATTERN, "")
           next "#{code}#{eol}" if type.nil?
 
-          "#{code.ljust(column)}  #=> dump_type: #{type.describe(:short)}#{eol}"
+          "#{code.ljust(column)}  #=> #{type.describe(:short)}#{eol}"
         end.join
       end
 
@@ -143,11 +169,46 @@ module Rigor
         widths.max || 0
       end
 
-      def render(annotated, color:)
+      def render(annotated, color:, bat: nil)
         return annotated unless color
         return annotated unless Prism.parse(annotated).success?
 
-        PrismColorizer.colorize(annotated)
+        rendered = render_with_bat(annotated, forced: bat) unless bat == false
+        rendered || PrismColorizer.colorize(annotated)
+      end
+
+      # Pipes the annotated source through `bat` and returns its
+      # highlighted output, or nil when bat is unavailable or
+      # fails (broken install, killed mid-write) — the caller
+      # falls back to {PrismColorizer}. An explicit `--bat` with
+      # no bat on PATH warns instead of failing silently.
+      def render_with_bat(annotated, forced: nil)
+        executable = bat_executable
+        if executable.nil?
+          @err.puts("annotate: --bat requested but no `bat` executable found on PATH") if forced
+          return nil
+        end
+
+        output = IO.popen([executable, *BAT_ARGS], "r+") do |io|
+          io.write(annotated)
+          io.close_write
+          io.read
+        end
+        return nil unless $CHILD_STATUS&.success?
+
+        output.empty? ? nil : output
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      def bat_executable
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+          next if dir.empty?
+
+          candidate = File.join(dir, "bat")
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+        end
+        nil
       end
     end
 
@@ -203,11 +264,30 @@ module Rigor
         widest_per_line(program).each do |line, node|
           next if by_line.key?(line)
 
-          type = type_of(node)
+          type = node.is_a?(Prism::BlockParametersNode) ? block_params_type(node) : type_of(node)
           by_line[line] = type unless type.nil?
         end
       end
 
+      # A `do |i|` header line's widest node is its BlockParametersNode —
+      # not an expression, so evaluating it would only echo the
+      # `Dynamic[top]` fallback. Annotate the line with the parameters'
+      # inferred bindings instead (the single param's type, or a tuple
+      # for multi-param blocks); decline (nil) when any param has no
+      # plain name or no recorded binding, leaving the line bare.
+      def block_params_type(params_node)
+        inner = params_node.parameters
+        return nil if inner.nil? || inner.requireds.empty?
+
+        scope = @scope_index[params_node]
+        types = inner.requireds.map do |param|
+          return nil unless param.respond_to?(:name)
+
+          scope.local(param.name) or return nil
+        end
+        types.size == 1 ? types.first : Type::Combinator.tuple_of(*types)
+      end
+
       def widest_per_line(program)
         widest = {}
         walk(program) do |node|
@@ -231,8 +311,13 @@ module Rigor
         node.compact_child_nodes.each { |child| walk(child, &block) }
       end
 
+      # Types the node through the flow evaluator (not the bare
+      # expression typer) under its recorded entry scope, so flow-only
+      # forms type as the engine sees them — `i += 1` dispatches `+` on
+      # `i`'s binding (`Integer`, post-fixpoint) instead of echoing the
+      # RHS literal's `1`.
       def type_of(node)
-        @scope_index[node].type_of(node)
+        Inference::StatementEvaluator.new(scope: @scope_index[node]).evaluate(node).first
       rescue StandardError
         nil
       end

data/lib/rigor/cli/check_command.rb

@@ -473,6 +473,9 @@ module Rigor
         @err.puts("  recursion-guard hits:      #{counts[Inference::BudgetTrace::RECURSION_GUARD]}")
         @err.puts("  ancestor-walk-limit hits:  #{counts[Inference::BudgetTrace::ANCESTOR_WALK_LIMIT]}")
         @err.puts("  hkt-fuel-exhausted hits:   #{counts[Inference::BudgetTrace::HKT_FUEL_EXHAUSTED]}")
+        @err.puts("  recursion-unroll-fuel hits: #{counts[Inference::BudgetTrace::RECURSION_UNROLL_FUEL]}")
+        @err.puts("  recursion-fixpoint-cap hits: #{counts[Inference::BudgetTrace::RECURSION_FIXPOINT_CAP]}")
+        @err.puts("  block-writeback-cap hits:  #{counts[Inference::BudgetTrace::BLOCK_WRITEBACK_CAP]}")
         write_budget_distributions
       end
 

data/lib/rigor/cli/plugins_command.rb

@@ -30,7 +30,7 @@ module Rigor
     # - every manifest-declared extension surface
     #   (`open_receivers:` / `owns_receivers:` / `produces:` /
     #   `consumes:` / `block_as_methods:` / `heredoc_templates:` /
-    #   `trait_registries:` / `external_files:` /
+    #   `trait_registries:` /
     #   `type_node_resolvers:` / `hkt_registrations:` /
     #   `hkt_definitions:` / `protocol_contracts:` /
     #   `source_rbs_synthesizer:`);
@@ -233,7 +233,6 @@ module Rigor
           block_as_methods: manifest.block_as_methods.size,
           heredoc_templates: manifest.heredoc_templates.size,
           trait_registries: manifest.trait_registries.size,
-          external_files: manifest.external_files.size,
           type_node_resolvers: manifest.type_node_resolvers.size,
           hkt_registrations: manifest.hkt_registrations.size,
           hkt_definitions: manifest.hkt_definitions.size,
@@ -257,7 +256,6 @@ module Rigor
           block_as_methods: 0,
           heredoc_templates: 0,
           trait_registries: 0,
-          external_files: 0,
           type_node_resolvers: 0,
           hkt_registrations: 0,
           hkt_definitions: 0,
@@ -337,7 +335,7 @@ module Rigor
             signature_paths: [],
             open_receivers: [], owns_receivers: [], produces: [], consumes: [],
             block_as_methods: 0, heredoc_templates: 0, trait_registries: 0,
-            external_files: 0, type_node_resolvers: 0,
+            type_node_resolvers: 0,
             hkt_registrations: 0, hkt_definitions: 0,
             protocol_contracts: 0, source_rbs_synthesizer: false,
             node_rule_types: [], dynamic_return_receivers: [], type_specifier_methods: [],

data/lib/rigor/cli/plugins_renderer.rb

@@ -209,7 +209,6 @@ module Rigor
         parts << "block_as_methods=#{row[:block_as_methods]}" if row[:block_as_methods].positive?
         parts << "heredoc_templates=#{row[:heredoc_templates]}" if row[:heredoc_templates].positive?
         parts << "trait_registries=#{row[:trait_registries]}" if row[:trait_registries].positive?
-        parts << "external_files=#{row[:external_files]}" if row[:external_files].positive?
         return [] if parts.empty?
 
         ["        macro substrate: #{parts.join(', ')}"]
@@ -233,7 +232,6 @@ module Rigor
           "block_as_methods" => row[:block_as_methods],
           "heredoc_templates" => row[:heredoc_templates],
           "trait_registries" => row[:trait_registries],
-          "external_files" => row[:external_files],
           "type_node_resolvers" => row[:type_node_resolvers],
           "hkt_registrations" => row[:hkt_registrations],
           "hkt_definitions" => row[:hkt_definitions],

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+require_relative "../bleeding_edge"
+require_relative "../configuration"
+require_relative "command"
+
+module Rigor
+  class CLI
+    # Executes `rigor show-bleedingedge` (ADR-50 § WD2).
+    #
+    # Prints the bleeding-edge overlay — the Rigor-maintained set of the
+    # next major's queued changes ({Rigor::BleedingEdge}) — as an
+    # explicit list, and reports which of them the project's
+    # `bleeding_edge:` configuration adopts. The overlay is empty in this
+    # release, so the command currently reports an empty set; it becomes
+    # the inspection surface ADR-50 describes once a feature is queued.
+    #
+    # Read-only: it loads `.rigor.yml` to resolve the active selection
+    # but runs no analysis.
+    class ShowBleedingedgeCommand < Command
+      USAGE = "Usage: rigor show-bleedingedge [options]"
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        configuration = load_configuration(options)
+        return CLI::EXIT_USAGE if configuration.nil?
+
+        case options.fetch(:format)
+        when "json" then render_json(configuration)
+        else render_text(configuration)
+        end
+        0
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", config: nil }
+        OptionParser.new do |opt|
+          opt.banner = USAGE
+          opt.on("--format=FORMAT", %w[text json], "Output format (text | json). Default: text.") do |fmt|
+            options[:format] = fmt
+          end
+          opt.on("--config=PATH", "Path to a .rigor.yml (default: auto-discovery).") do |path|
+            options[:config] = path
+          end
+        end.parse!(@argv)
+        options
+      end
+
+      def load_configuration(options)
+        Configuration.load(options.fetch(:config))
+      rescue StandardError => e
+        @err.puts("show-bleedingedge: could not load configuration: #{e.message}")
+        nil
+      end
+
+      def render_json(configuration)
+        selector = configuration.bleeding_edge
+        @out.puts(JSON.pretty_generate(
+                    "overlay" => BleedingEdge.features.map(&:to_h),
+                    "selector" => configuration.to_h.fetch("bleeding_edge"),
+                    "active" => BleedingEdge.active_features(selector).map(&:id),
+                    "unknown_selected" => BleedingEdge.unknown_selected_ids(selector)
+                  ))
+      end
+
+      def render_text(configuration)
+        @out.puts("Bleeding-edge overlay (ADR-50 § WD2)")
+        @out.puts("")
+        if BleedingEdge.features.empty?
+          render_empty_overlay
+        else
+          render_overlay
+        end
+        @out.puts("")
+        render_selection(configuration)
+      end
+
+      def render_empty_overlay
+        @out.puts("The overlay is empty in this release — no features are queued for")
+        @out.puts("the next major. The `bleeding_edge:` mechanism is wired and ready;")
+        @out.puts("there is simply nothing to adopt yet.")
+      end
+
+      def render_overlay
+        @out.puts("#{BleedingEdge.features.length} feature(s) queued for the next major:")
+        @out.puts("")
+        BleedingEdge.features.each do |feature|
+          @out.puts("  #{feature.id}")
+          @out.puts("    #{feature.summary}")
+          feature.severity_overrides.each do |rule, severity|
+            @out.puts("    severity: #{rule} → :#{severity}")
+          end
+        end
+      end
+
+      def render_selection(configuration)
+        selector = configuration.bleeding_edge
+        active = BleedingEdge.active_features(selector).map(&:id)
+        @out.puts("Your configuration adopts: #{active.empty? ? '(none)' : active.join(', ')}")
+
+        unknown = BleedingEdge.unknown_selected_ids(selector)
+        return if unknown.empty?
+
+        @out.puts("Selected but not in this overlay (ignored): #{unknown.join(', ')}")
+      end
+    end
+  end
+end

data/lib/rigor/cli/triage_command.rb

@@ -21,7 +21,7 @@ module Rigor
     # command, not a gate (`rigor check` remains the gate).
     class TriageCommand < Command
       USAGE = "Usage: rigor triage [options] [paths]"
-      DEFAULT_SECTIONS = %i[distribution hotspots hints].freeze
+      DEFAULT_SECTIONS = %i[distribution selectors hotspots hints].freeze
 
       # @return [Integer] CLI exit status (always 0).
       def run
@@ -46,8 +46,11 @@ module Rigor
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
           opts.on("--top=N", Integer, "Hotspot-file count (default 10)") { |v| options[:top] = v }
           opts.on("--hints-only", "Print only the heuristic-hints section") { options[:sections] = %i[hints] }
-          opts.on("--no-hints", "Print distribution + hotspots only") do
-            options[:sections] = %i[distribution hotspots]
+          opts.on("--no-hints", "Print distribution + selectors + hotspots only") do
+            options[:sections] = %i[distribution selectors hotspots]
+          end
+          opts.on("--selectors-only", "Print only the class/method selectors section") do
+            options[:sections] = %i[selectors]
           end
         end.parse!(@argv)
         validate!(options)

data/lib/rigor/cli/triage_renderer.rb

@@ -10,10 +10,11 @@ module Rigor
     # triage` text report or as `--format json`.
     class TriageRenderer
       BAR_WIDTH = 24
+      SELECTOR_ROWS = 15 # text-output cap; `--format json` carries the full list
 
       def initialize(report, sections:)
         @report = report
-        @sections = sections # subset of %i[distribution hotspots hints]
+        @sections = sections # subset of %i[distribution selectors hotspots hints]
       end
 
       def json
@@ -23,6 +24,7 @@ module Rigor
       def text
         blocks = []
         blocks << distribution_block if @sections.include?(:distribution)
+        blocks << selectors_block    if @sections.include?(:selectors)
         blocks << hotspots_block     if @sections.include?(:hotspots)
         blocks << hints_block        if @sections.include?(:hints)
         "#{blocks.join("\n\n")}\n"
@@ -42,6 +44,18 @@ module Rigor
         lines.join("\n")
       end
 
+      def selectors_block
+        return "Selectors — by class / method\n  (none)" if @report.selectors.empty?
+
+        lines = ["Selectors — by class / method (top #{SELECTOR_ROWS}; full list in --format json)"]
+        @report.selectors.first(SELECTOR_ROWS).each do |sel|
+          label = sel.receiver ? "#{sel.receiver}##{sel.method_name}" : sel.method_name
+          lines << format("  %<label>-44s %<count>5d  %<files>3d file(s)",
+                          label: label, count: sel.count, files: sel.files)
+        end
+        lines.join("\n")
+      end
+
       def hotspots_block
         return "Hotspot files\n  (none)" if @report.hotspots.empty?
 

data/lib/rigor/cli.rb

@@ -38,7 +38,8 @@ module Rigor
       "plugins" => :run_plugins,
       "plugin" => :run_plugin,
       "playground" => :run_playground,
-      "skill" => :run_skill
+      "skill" => :run_skill,
+      "show-bleedingedge" => :run_show_bleedingedge
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -289,6 +290,12 @@ module Rigor
       CLI::PluginCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_show_bleedingedge
+      require_relative "cli/show_bleedingedge_command"
+
+      CLI::ShowBleedingedgeCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def help
       <<~HELP
         Usage: rigor <command> [options]
@@ -311,6 +318,7 @@ module Rigor
           plugin     Browse bundled plugin source as worked examples (list/path/print/root)
           playground Start the browser playground (requires rigor-playground gem)
           skill      List or print bundled Agent Skills (rigor-project-init, ...)
+          show-bleedingedge  Show the bleeding-edge overlay + what your config adopts (ADR-50)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/configuration/severity_profile.rb

@@ -130,14 +130,26 @@ module Rigor
       #   Keys are canonical rule ids; values are
       #   {VALID_SEVERITIES} symbols. Family-wildcard keys
       #   (`call`) match every rule under that prefix.
+      # @param bleeding_edge_overrides [Hash{String => Symbol}] the
+      #   severity map imposed by the active ADR-50 § WD2 bleeding-edge
+      #   features ({Rigor::BleedingEdge.severity_overrides_for}).
+      #   Consulted *below* the user's own `overrides` (so an explicit
+      #   `severity_overrides:` entry, exact or family wildcard, always
+      #   wins) and *above* the profile table. Exact rule ids only — the
+      #   overlay never carries family wildcards. Empty while the
+      #   overlay is unpopulated, so the default leaves resolution
+      #   bit-for-bit unchanged.
       # @return [Symbol] the resolved severity. Returns `:off` to
       #   mean "drop the diagnostic entirely".
-      def resolve(rule:, authored_severity:, profile: DEFAULT_PROFILE, overrides: {})
+      def resolve(rule:, authored_severity:, profile: DEFAULT_PROFILE, overrides: {}, bleeding_edge_overrides: {})
         return authored_severity if rule.nil?
 
         override = overrides[rule] || family_override(rule, overrides)
         return override.to_sym if override
 
+        bleeding = bleeding_edge_overrides[rule]
+        return bleeding.to_sym if bleeding
+
         profile_table = PROFILES[profile] || PROFILES.fetch(DEFAULT_PROFILE)
         profile_table.fetch(rule, authored_severity)
       end

data/lib/rigor/configuration.rb

@@ -2,6 +2,7 @@
 
 require "yaml"
 
+require_relative "bleeding_edge"
 require_relative "configuration/dependencies"
 require_relative "configuration/severity_profile"
 
@@ -87,6 +88,15 @@ module Rigor
       },
       "severity_profile" => "balanced",
       "severity_overrides" => {},
+      # ADR-50 § WD2 — bleeding-edge overlay opt-in. Selects which of
+      # the *next major's* queued changes ({Rigor::BleedingEdge}) this
+      # project adopts early. Orthogonal to `severity_profile:`. Accepts
+      # `false` (default — adopt none), `true` (adopt the whole
+      # overlay), a list of feature ids (adopt only those), or
+      # `{ all: true, except: [ids] }` (adopt all but the named). The
+      # overlay is empty today, so every form is currently a no-op; it
+      # becomes live when the first discipline is queued for a major.
+      "bleeding_edge" => false,
       "dependencies" => {
         "source_inference" => [],
         "budget_per_gem" => Configuration::Dependencies::DEFAULT_BUDGET_PER_GEM
@@ -181,6 +191,7 @@ module Rigor
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
+                :bleeding_edge, :bleeding_edge_severity_overrides,
                 :dependencies, :parallel_workers,
                 :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
                 :rbs_collection_lockfile, :rbs_collection_auto_detect,
@@ -355,6 +366,10 @@ module Rigor
       @severity_overrides = coerce_severity_overrides(
         data.fetch("severity_overrides", DEFAULTS.fetch("severity_overrides"))
       )
+      @bleeding_edge = coerce_bleeding_edge(
+        data.fetch("bleeding_edge", DEFAULTS.fetch("bleeding_edge"))
+      )
+      @bleeding_edge_severity_overrides = BleedingEdge.severity_overrides_for(@bleeding_edge)
       @dependencies = Dependencies.from_h(
         data.fetch("dependencies", DEFAULTS.fetch("dependencies"))
       )
@@ -383,7 +398,7 @@ module Rigor
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-    def to_h # rubocop:disable Metrics/MethodLength
+    def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
@@ -405,6 +420,7 @@ module Rigor
         },
         "severity_profile" => severity_profile.to_s,
         "severity_overrides" => severity_overrides.to_h { |k, v| [k, v.to_s] },
+        "bleeding_edge" => bleeding_edge_to_h,
         "dependencies" => dependencies.to_h,
         "parallel" => {
           "workers" => parallel_workers
@@ -566,5 +582,45 @@ module Rigor
         [k.to_s, sym]
       end.freeze
     end
+
+    # ADR-50 § WD2 — normalizes the `bleeding_edge:` selector to a
+    # canonical `{ "mode" => … }` hash (interpreted by
+    # {Rigor::BleedingEdge}). Validates *shape* only; membership against
+    # the overlay is intentionally NOT checked here (an unknown id stays
+    # inert, like an unknown `severity_overrides:` rule). Deep-frozen so
+    # the Configuration stays `Ractor.shareable?`.
+    def coerce_bleeding_edge(value)
+      case value
+      when nil, false then { "mode" => "none" }
+      when true then { "mode" => "all" }
+      when Array then { "mode" => "list", "ids" => value.map(&:to_s).freeze }
+      when Hash then coerce_bleeding_edge_hash(value)
+      else
+        raise ArgumentError,
+              "bleeding_edge must be true, false, a list of feature ids, " \
+              "or { all: true, except: [...] }, got #{value.inspect}"
+      end.freeze
+    end
+
+    def coerce_bleeding_edge_hash(value)
+      hash = value.to_h { |k, v| [k.to_s, v] }
+      if hash.fetch("all", false) == true
+        { "mode" => "all", "except" => Array(hash["except"]).map(&:to_s).freeze }
+      else
+        { "mode" => "none" }
+      end
+    end
+
+    # Renders the normalized selector back into the user-facing
+    # `bleeding_edge:` form for `#to_h` round-trips.
+    def bleeding_edge_to_h
+      case bleeding_edge["mode"]
+      when "all"
+        except = bleeding_edge["except"] || []
+        except.empty? || { "all" => true, "except" => except }
+      when "list" then bleeding_edge["ids"] || []
+      else false
+      end
+    end
   end
 end

data/lib/rigor/environment/rbs_loader.rb

@@ -88,6 +88,15 @@ module Rigor
           vendored_gem_sig_paths.each do |path|
             rbs_loader.add(path: path) if path.directory?
           end
+          # Rigor-owned core overlay — loaded LAST so an upstream
+          # declaration always wins on conflict; these reopenings only
+          # fill genuine holes (e.g. `Numeric#to_f`/`to_i`/`to_r`, which
+          # upstream RBS declares on the concrete subclasses but not on
+          # the abstract `Numeric` that Rigor's arithmetic-chain widening
+          # produces).
+          core_overlay_sig_paths.each do |path|
+            rbs_loader.add(path: path) if path.directory?
+          end
           env = RBS::Environment.from_loader(rbs_loader)
           add_virtual_rbs(env, virtual_rbs)
           synthesize_missing_namespaces(env)
@@ -298,6 +307,22 @@ module Rigor
         ).freeze
         private_constant :VENDORED_GEM_SIGS_ROOT
 
+        # Rigor-owned core-overlay RBS (`data/core_overlay/`). Reopens
+        # Ruby core classes to add methods upstream `ruby/rbs` omits but
+        # which every concrete value answers at runtime — loaded last so
+        # upstream always wins on conflict. Public so the cache descriptor
+        # can digest these files into the env-blob key.
+        CORE_OVERLAY_SIGS_ROOT = File.expand_path(
+          "../../../data/core_overlay",
+          __dir__
+        ).freeze
+
+        def core_overlay_sig_paths
+          return [] unless File.directory?(CORE_OVERLAY_SIGS_ROOT)
+
+          [Pathname(CORE_OVERLAY_SIGS_ROOT)]
+        end
+
         def vendored_gem_sig_paths
           return [] unless File.directory?(VENDORED_GEM_SIGS_ROOT)