rigortype 0.1.15 → 0.1.16

data/lib/rigor/cli.rb

@@ -78,11 +78,7 @@ module Rigor
     end
 
     def run_check
-      require_relative "analysis/runner"
-      require_relative "analysis/buffer_binding"
-      require_relative "analysis/baseline"
-      require_relative "cache/store"
-
+      load_check_dependencies
       options = parse_check_options
       buffer = resolve_buffer_binding(options)
       return EXIT_USAGE if buffer == :usage_error
@@ -100,6 +96,7 @@ module Rigor
 
       write_result(result, options.fetch(:format))
       write_run_stats(result.stats) if result.stats
+      write_trace_appendices
       write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
 
       exit_code = result.success? ? 0 : 1
@@ -402,6 +399,139 @@ module Rigor
       stats.format(@err)
     end
 
+    # Opt-in developer diagnostics printed after the run: the
+    # inference-cutoff trace (RIGOR_BUDGET_TRACE) and the heap-attribution
+    # profile (RIGOR_HEAP_PROFILE). Each gates itself, so this is a no-op
+    # on a normal run.
+    def write_trace_appendices
+      write_budget_trace
+      write_heap_profile
+    end
+
+    # Dumps the opt-in inference-cutoff counters (RIGOR_BUDGET_TRACE).
+    # These are the hard-coded "budget" guards that silently degrade
+    # to `Dynamic[top]` / a fallback bound — counting them shows where
+    # inference actually stopped. Process-global counters: meaningful
+    # only on a single-process run (`--workers 0`), since they do not
+    # cross fork boundaries.
+    def write_budget_trace
+      return unless Inference::BudgetTrace.enabled?
+
+      counts = Inference::BudgetTrace.snapshot
+      @err.puts("")
+      @err.puts("Inference cutoffs (RIGOR_BUDGET_TRACE; --workers 0 for an exact count)")
+      @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]}")
+      write_budget_distributions
+    end
+
+    # Dumps the read-only size distributions (ADR-41 Slice 2a). These
+    # observe how large unions actually get, with no cap enforced — the
+    # data the `union_size` budget default should be chosen from. The
+    # `over` thresholds bracket the TypeProf prior (10) and Rigor's spec
+    # default (24).
+    def write_budget_distributions
+      summary = Inference::BudgetTrace.summarize(Inference::BudgetTrace::UNION_ARITY, over: [10, 24, 40])
+      pct = summary[:percentiles]
+      @err.puts("  union arity:  n=#{summary[:count]} max=#{summary[:max]} " \
+                "p50=#{pct[:p50]} p90=#{pct[:p90]} p99=#{pct[:p99]}")
+      over = summary[:over]
+      @err.puts("    unions ≥10: #{over[10]}  ≥24: #{over[24]}  ≥40: #{over[40]}")
+    end
+
+    # Dumps a live-heap class breakdown (RIGOR_HEAP_PROFILE) — retained
+    # objects by class after a forced GC, ranked by total memsize. The
+    # tool for attributing where the analyzer's resident memory goes
+    # (ADR-41 Slice 2b): it answers whether the heap is type carriers,
+    # RBS objects, Prism nodes, or fact-store Hashes/Strings. Walking the
+    # whole heap is slow — a dev probe, not a normal diagnostic. Run
+    # single-process (`--workers 0`) so the parent heap is the analysis
+    # heap; the gem is required lazily so a normal run never loads it.
+    def write_heap_profile
+      return if ENV["RIGOR_HEAP_PROFILE"].to_s.empty?
+
+      by_class, total = tally_live_heap
+      @err.puts("")
+      @err.puts("Heap profile (RIGOR_HEAP_PROFILE; live objects after GC, by class)")
+      @err.puts("  total tracked: #{heap_mb(total)} across #{by_class.size} classes")
+      by_class.sort_by { |_, (_, bytes)| -bytes }.first(30).each do |name, (count, bytes)|
+        @err.puts("  #{heap_mb(bytes).rjust(10)}  #{count.to_s.rjust(9)} obj  #{name}")
+      end
+      write_string_allocation_sites
+    end
+
+    # Loads the analysis-path dependencies lazily (so non-check commands
+    # stay light) and starts heap-allocation tracing if requested, before
+    # any analysis object is allocated.
+    def load_check_dependencies
+      require_relative "analysis/runner"
+      require_relative "analysis/buffer_binding"
+      require_relative "analysis/baseline"
+      require_relative "cache/store"
+      start_heap_trace_if_requested
+    end
+
+    # Starts allocation tracing (RIGOR_HEAP_TRACE) as early as possible so
+    # the heap profile can attribute retained Strings to their allocation
+    # `file:line`. Very high overhead — run on a small file subset only.
+    def start_heap_trace_if_requested
+      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+
+      require "objspace"
+      ObjectSpace.trace_object_allocations_start
+    end
+
+    # When RIGOR_HEAP_TRACE is on, groups the live String objects by their
+    # allocation site (`sourcefile:sourceline`) and prints the top sites by
+    # count — pinpointing which engine code retains the millions of strings
+    # that dominate the large-app heap (ADR-41 Slice 2b). Strings allocated
+    # before tracing started report `(pre-trace)`.
+    def write_string_allocation_sites
+      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+
+      by_site = Hash.new(0)
+      ObjectSpace.each_object(String) do |str|
+        file = ObjectSpace.allocation_sourcefile(str)
+        line = ObjectSpace.allocation_sourceline(str)
+        by_site[file ? "#{file}:#{line}" : "(pre-trace)"] += 1
+      end
+      @err.puts("")
+      @err.puts("  String allocation sites (top 25 by live count)")
+      by_site.sort_by { |_, n| -n }.first(25).each do |site, n|
+        @err.puts("  #{n.to_s.rjust(9)}  #{site}")
+      end
+    end
+
+    # Walks the whole live heap (after a forced GC) and tallies
+    # `{class_name => [count, memsize]}` plus the grand total. Returns
+    # `[by_class, total]`. Slow — a dev probe only.
+    def tally_live_heap
+      require "objspace"
+      GC.start
+      by_class = Hash.new { |h, k| h[k] = [0, 0] }
+      total = 0
+      ObjectSpace.each_object do |obj|
+        size = ObjectSpace.memsize_of(obj)
+        entry = by_class[heap_class_name(obj)]
+        entry[0] += 1
+        entry[1] += size
+        total += size
+      end
+      [by_class, total]
+    end
+
+    def heap_class_name(obj)
+      klass = Object.instance_method(:class).bind_call(obj)
+      klass.name || klass.inspect
+    rescue StandardError
+      "(unknown)"
+    end
+
+    def heap_mb(bytes)
+      Kernel.format("%.1f MB", bytes / 1_048_576.0)
+    end
+
     def write_cache_stats(cache_root, runtime_store)
       inv = Cache::Store.disk_inventory(root: cache_root)
 

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
@@ -546,6 +763,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"

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/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/expression_typer.rb

@@ -5,6 +5,7 @@ require "prism"
 require_relative "../type"
 require_relative "../ast"
 require_relative "block_parameter_binder"
+require_relative "budget_trace"
 require_relative "fallback"
 require_relative "indexed_narrowing"
 require_relative "macro_block_self_type"
@@ -1358,7 +1359,10 @@ module Rigor
 
           seen[current] = true
           visited += 1
-          return nil if visited > ANCESTOR_WALK_LIMIT
+          if visited > ANCESTOR_WALK_LIMIT
+            BudgetTrace.hit(BudgetTrace::ANCESTOR_WALK_LIMIT)
+            return nil
+          end
 
           found = scope.user_def_for(current, method_name)
           return found if found
@@ -1432,7 +1436,10 @@ module Rigor
         # carrier for top-level / DSL-block defs) printable.
         signature = [receiver.describe(:short), def_node.name]
         stack = (Thread.current[INFERENCE_GUARD_KEY] ||= [])
-        return Type::Combinator.untyped if stack.include?(signature)
+        if stack.include?(signature)
+          BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+          return Type::Combinator.untyped
+        end
 
         stack.push(signature)
         begin

data/lib/rigor/inference/hkt_reducer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "hkt_body"
+require_relative "budget_trace"
 
 module Rigor
   module Inference
@@ -71,6 +72,7 @@ module Rigor
             walk(definition.body_tree, bindings: bindings_for(definition, app.args), state: state) || app.bound
           end
         rescue FuelExhausted
+          BudgetTrace.hit(BudgetTrace::HKT_FUEL_EXHAUSTED)
           app.bound
         end
       end