Module: Rigor::Inference::BudgetTrace

Defined in:
lib/rigor/inference/budget_trace.rb

Overview

Opt-in counters for the hard-coded inference cutoffs — the “budget” guards that silently return ‘Dynamic` / `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` (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`.

  • RECURSION_UNROLL_FUEL — the constant-arg recursion unroll (ADR-55 slice 1) exhausted its per-entry fuel and fell back to the plain ‘(receiver, method)` guard (in-cycle call → `Dynamic`).

  • RECURSION_FIXPOINT_CAP — the fixpoint return-summary iteration (ADR-55 slice 2) hit its 3-evaluation cap without converging and collapsed the summary to ‘untyped` (today’s behaviour).

Enabled only when ‘RIGOR_BUDGET_TRACE` is set (to any non-empty value) in the environment, or via BudgetTrace.enable! in tests. When disabled, BudgetTrace.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.

Constant Summary collapse

RECURSION_GUARD = 
:recursion_guard
ANCESTOR_WALK_LIMIT = 
:ancestor_walk_limit
HKT_FUEL_EXHAUSTED = 
:hkt_fuel_exhausted
RECURSION_UNROLL_FUEL =

‘ExpressionTyper#infer_user_method_return` exhausted its constant-arg unroll fuel (ADR-55 slice 1) and fell back to the plain `(receiver, method)` recursion guard — i.e. the in-cycle call widened to `Dynamic` exactly as it does without the unroll.

:recursion_unroll_fuel
RECURSION_FIXPOINT_CAP =

‘ExpressionTyper#infer_user_method_return` ran the fixpoint return-summary iteration (ADR-55 slice 2) to its 3-evaluation cap without reaching convergence and collapsed the summary to `untyped` — the in-cycle result widens to `Dynamic` exactly as it does without the fixpoint.

:recursion_fixpoint_cap
BLOCK_WRITEBACK_CAP =

‘BodyFixpoint#converge` (ADR-56 slice A — non-escaping block captured-local write-back) ran its 3-evaluation cap without the written local’s join converging and collapsed that local to ‘Dynamic` (the escaping-block floor). Shared by slice B’s loop-body fixpoint.

:block_writeback_cap
CATEGORIES = 
[
  RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED, RECURSION_UNROLL_FUEL,
  RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP
].freeze
UNION_ARITY =

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
DISTRIBUTION_CATEGORIES = 
[UNION_ARITY].freeze

Class Method Summary collapse

Class Method Details

.disable! ⇒ Object 



94
95
96
 
# File 'lib/rigor/inference/budget_trace.rb', line 94

def disable!
  @enabled = false
end

.distribution(category) ⇒ Object

Frozen ‘=> count` histogram for a distribution category.



123
124
125
 
# File 'lib/rigor/inference/budget_trace.rb', line 123

def distribution(category)
  @mutex.synchronize { @distributions[category].dup.freeze }
end

.enable! ⇒ Object

Test / programmatic toggles. Production enablement is the ‘RIGOR_BUDGET_TRACE` env var read once at load time.



90
91
92
 
# File 'lib/rigor/inference/budget_trace.rb', line 90

def enable!
  @enabled = true
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/rigor/inference/budget_trace.rb', line 84

def enabled?
  @enabled
end

.hit(category) ⇒ Object

Records one firing of ‘category`. No-op (one boolean check) when tracing is disabled.



100
101
102
103
104
 
# File 'lib/rigor/inference/budget_trace.rb', line 100

def hit(category)
  return unless @enabled

  @mutex.synchronize { @counts[category] += 1 }
end

.observe(category, value) ⇒ Object

Records one observation of ‘value` (an Integer size) into `category`’s histogram. No-op (one boolean check) when disabled.



116
117
118
119
120
 
# File 'lib/rigor/inference/budget_trace.rb', line 116

def observe(category, value)
  return unless @enabled

  @mutex.synchronize { @distributions[category][value] += 1 }
end

.percentile(hist, total, fraction) ⇒ Object

Nearest-rank percentile over a ‘=> count` histogram without materialising the full sample.



146
147
148
149
150
151
152
153
154
 
# File 'lib/rigor/inference/budget_trace.rb', line 146

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

.reset ⇒ Object 



156
157
158
159
160
161
 
# File 'lib/rigor/inference/budget_trace.rb', line 156

def reset
  @mutex.synchronize do
    @counts.clear
    @distributions.clear
  end
end

.snapshot ⇒ Object

Frozen snapshot of the current counts, every known category present (zero-filled) so consumers can render a stable table.



108
109
110
111
112
 
# File 'lib/rigor/inference/budget_trace.rb', line 108

def snapshot
  @mutex.synchronize do
    CATEGORIES.to_h { |category| [category, @counts[category]] }.freeze
  end
end

.summarize(category, over: []) ⇒ Object

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.



131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/rigor/inference/budget_trace.rb', line 131

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