quota-interpretation

Quota Interpretation, Pace & Output Models

This document specifies the mathematics and presentation rules for quota interpretation, runway derivation, pace calculations, and output format tiering in quota-axi.

Quota Availability & Bound Conflicts

Implemented in src/interpretation.ts:

• Effective Availability: Analyzes provider windows across all scopes (all_models, product scopes, model scopes).
• Bound Conflict Detection:
  • availability() accepts an optional own-windows argument.
  • When every window metered strictly for a scope reports remaining allowance, but an inherited account-wide window reports zero, quota-axi publishes effectiveAvailability[].boundConflict and reports the scope status as unknown rather than asserting exhausted_now or effective 0.
  • Used for Codex model windows (additional_rate_limits/rateLimitsByLimitId). Other providers keep their account bounds unless empirical proof of non-enforcement exists.

Pace & Runway Calculations

Implemented in src/pace.ts:

• Cycle-Average Pace: Every projection assumes cycle-average consumption across the active window. There is no projectionBasis field anywhere in the API model.
• Reserve Percentage Points (reservePercentPoints):
  • Quantifies how usage tracks against elapsed window time.
  • Positive values indicate usage is tracking behind the elapsed time clock (headroom remaining).
  • Negative values indicate usage is running ahead of the reset clock (burn rate higher than cycle average).
• Effective Usable Runway: Aggregates all authoritative bounds to determine time until exhaustion, preserving uncertainty if any binding window lacks timing metadata. Runway is dynamic and never cached.
• Selection Signal (effectiveAvailability[].selection):
  • Computed purely from reported figures via summarizeEffectiveSelection in src/pace.ts.
  • Published field name is centralized in SELECTION_SCALAR_KEY in src/types.ts.
  • If any bounding window lacks usable pace data, the whole scope is deemed unmeasurable (no scalar published, unmeasurableWindowIds listed). A not-yet-triggered zero-use window (no resetsAt plus zero usage) is fully available and is excluded from the weighted mean instead of blocking; when every bounding window is untriggered the scope publishes no scalar and reports unknown with no unmeasurableWindowIds.
  • Data only: quota-axi never routes, recommends, or ranks winners.