6krrt/plans/quota-balance-and-burn-rate.md

Quota: track balance and burn rate, not percentage of plan

Status: done -- balance/burn/runway per provider

Status: FINAL — decision-complete. Written 2026-09-04 from live data.

The modelling error

metrics.quota_burn reports usage as a fraction of plan_kwh_per_period, and coverage.warnings renders it as:

metered usage is 146% of the 6.25 kWh plan allowance. A quota is a wall, not a bill — requests fail rather than costing more.

That claim is false for this account. Usage sailed past 100% and nothing failed, because the provider bills overage against a credit balance. The warning is simultaneously alarming and unactionable: it says a wall was hit when no wall exists, and it offers no number an operator can act on.

Meanwhile the authoritative signal — the provider reports allowance_remaining_usd on every single response — is captured (config/schema.sql:156, read at src/dispatcher.py:1416), persisted to energy_observations, and then used by exactly one thing: seed_energy.py, for sweep accounting. Nothing watches it.

What the recorded data actually shows

Queried 2026-09-04 from energy_observations:

date	calls	balance range (USD)
2026-09-04	1,853	19.70 → 12.19
2026-09-03	174	19.95 → 19.70
2026-09-02	3,573	20.01 → 0.0071
2026-09-01	3,116	14.34 → 4.34

The 2026-09-02 provider outage is in the table. The balance walked down through $0.4991 → $0.4967 → $0.4924 at 05:54:26–05:54:32 and bottomed at $0.0071. The router observed the balance approaching zero, request by request, and said nothing. Hours of warning were available and discarded.

Current state: $12.19 remaining, burning $7.51 over 1,853 calls in 14.3 hours ≈ $0.52/hour ≈ ~23 hours of runway.

That is the sentence the dashboard should be showing. "146% of plan" is not.

Three defects, in order of value

1. The wrong signal

Warn on balance and projected time-to-zero, sourced from allowance_remaining_usd, not on percentage of a kWh plan.

• Headline: current balance, recent burn rate, projected hours remaining.
• Warn when projected runway drops below a configurable threshold (hours, not percent). Default it to something an operator can act within — a few hours.
• Keep the kWh plan figure as secondary context. It is still the right unit for the subscription; it is the wrong thing to alarm on.

The implementation trap, and it is the whole difficulty: a top-up makes the balance JUMP UP. On 2026-09-02 it went 0.0071 → 20.0071. A naive MAX - MIN over a window reports a burn of ~$20 when the real burn was ~$20 down plus a $20 credit. Compute burn from consecutive decreasing deltas only, or segment the series at every increase and use the most recent segment. A test must cover a window containing a top-up; getting this wrong produces a confidently wrong runway estimate, which is worse than none.

Handle allowance_remaining_usd IS NULL (older rows, and any response that omits it) by excluding those rows, not by treating them as zero.

2. The wrong window

quota_burn sums energy_kwh over a 30-day rolling window while the subscription resets monthly on objective.billing_reset_day (currently 6). Those are different periods, so the reported fraction does not correspond to the billing period it appears to describe. It also returns reset_date = today − 30 days, which is the rolling-window start named as if it were a billing reset — the same confusion billing_reset_day was added to fix in the admin modal.

Compute the kWh figure over the current billing period (since the most recent billing_reset_day), and rename the rolling-window field so it cannot be mistaken for a reset date. Keep the rolling figure if it is useful, but label it honestly.

3. The wrong words

"A quota is a wall, not a bill — requests fail rather than costing more" appears in the warning text and the same framing is in config/config.yaml (max_energy_per_request, plan_kwh_per_period comments) and in CLAUDE.md. It is demonstrably false for this account and it changes what an operator does: a wall means "stop", overage means "you are being billed, decide if that is fine."

Correct all three places. State plainly that overage is billed against a credit balance, and that plan_kwh_per_period gates nothing — verified: it appears only in metrics.py reporting and the admin allowlist.

Surfacing

• Admin dashboard quota chip: show balance and runway as the headline, percentage-of-plan demoted to detail.
• /metrics quota block gains the balance/burn fields alongside the existing ones. Do not remove existing keys — the TUI and admin snapshot read them.

Non-goals

• Do not gate or refuse requests on quota. plan_kwh_per_period gates nothing today and this plan does not change that. Refusing traffic because a local estimate says the balance is low would turn a billing question into an outage — and the estimate can be wrong (see the top-up trap).
• Do not add a second source of truth. allowance_remaining_usd is the provider's own number; do not reconstruct a balance from summed cost_usd.
• Do not touch max_energy_per_request behaviour.
• Do not change how energy_observations rows are written.

Success criteria

• /metrics quota reports current balance, burn rate over a stated window, and projected hours to zero, all derived from allowance_remaining_usd.
• A test with a top-up inside the window (balance increasing) produces a correct burn rate, not one inflated by the credit.
• A test with all-NULL allowance_remaining_usd degrades gracefully rather than reporting a zero balance.
• The kWh figure is computed over the current billing period, and no field named reset_date returns a rolling-window start.
• The "wall, not a bill" framing is corrected in metrics.py, config/config.yaml and CLAUDE.md, and states that plan_kwh_per_period gates nothing.
• The admin quota chip leads with balance and runway.
• Existing /metrics quota keys still present.
• Full suite green with local_energy.enabled both true and false.
• The user's config/config.local.yaml is byte-identical after the run (local_energy.enabled: true, tariff_usd_per_kwh: 0.159). Corrected 2026-09-04: this criterion previously said the tariff lines in config/config.yaml must stay uncommitted. That is stale — PR #26 moved deployment values into the gitignored overlay, so config/config.yaml is now clean and tracked. Note the consequence for this plan specifically: §3 edits comments in config/config.yaml, which is now an ordinary tracked edit to commit deliberately, not a file to tiptoe around. The file to protect is the overlay, and it is not in git history at all.

The pattern worth naming

This is the third plan in a row whose finding is "the signal was already recorded and nothing surfaced it" — after the capability-gated ceiling collapse and the unread route_decisions rejections. The router is good at capturing evidence and poor at putting it where an operator looks. Worth considering a general review of what is persisted versus what is displayed, rather than a fourth one-off detector.