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.

---

Output Formats & Tier Splitting

1. Default TOON Report (src/render.ts)

Structured into three concise decision blocks:

1. quota[]: One fully populated row per measurable scope.
2. exhaustion[]: Sparse block for finite-runway scopes, joined on provider + scope.
3. attention[]: Sparse block capturing every non-nominal condition (degraded sources, warnings, unmeasurable scopes, soft expiry).

Core Invariants:

• Every requested provider must appear in quota[] or attention[], except providers with positive evidence of absence, which default TOON omits and counts in a single help line; --full and an explicit --provider name them.
• quota[] rows preserve provider declaration order and are never metric-sorted.
• spendPriority renders literal unknown, never 0. An unknown or stale scope receives no quota[] row; any finite runway is preserved in attention[].

2. JSON Tier Splitting (--json vs --full)

• --json: Normalized quota model with derivation inputs demoted to --full.
• --full: Includes account identities, diagnostic logs, and per-source attempts.
• Demotion Rule: Demote at renderer serialization time only (quotaJsonReport in src/render.ts). The in-memory model retains all fields so --tui and --full have full context.

3. Human Terminal Interface (--tui)

• Pure card renderer in src/tui.ts; interactive live loop in src/tui-live.ts.
• Viewport Management: renderQuotaTui is height-independent. src/tui-viewport.ts (scrollFrame) windows the output to fit terminal dimensions, clipping oversized lines and providing scroll affordances without terminal overflow.
• Humanized Presentation:
  • through_reset renders as on pace ✓.
  • Pace is visualized via bar fill and ┃ marker (no multiple chip or legend).
  • Projected exhaustion displays as relative countdown (empty in Nd Nh).
  • Headline bar uses the binding window's own label (week, session, credits).

4. CLI Fast Path

• Bare -v, -V, or --version routes through axi-sdk-js/fast-path and the leaf src/version.ts.
• Dynamically imports src/cli.js so provider dependencies and network graph never load on version checks.