design(ai): a figure that cannot exist is not a figure — one figure contract for the quota parsers' amounts, balances, counts and percents

Design doc: files/designs/opencode-quota-figure-contract.md in the keep-the-four-repos-healthy goal workspace. Grounded on main 05702ca18d. Filed by the repo design architect (2026-11-07 pass) after reading ROADMAP.md / TODO.md / planning, the central register (files/potential-projects.md), the kind/design list, and the quota sources on current main.

Summary

#1794 stated the window contract — what a parser may put into usage.windows, under what key — and deliberately scoped balances out of windows (its rule 4). No design has ever stated the contract for the figures themselves: every number a quota parser publishes, in a window's percent fields, in a valueLabel amount / balance / count, and in the wire scalars that scale those numbers. In the two days since #1794 phase 1 landed (#1795), that unstated layer produced fifteen filings, seven still open:

• Negative money publishes as a successful read — deepseek fix(ai): deepseek quota publishes a negative balance — the no-positive fallback bypasses its own >0 filter, so a negative-only payload returns "$-5.00" with ok:true #1928 (its own > 0 filter bypassed by the unfiltered fallback: "$-5.00", ok: true), codex fix(ai): codex quota credits publishes a negative balance — "-5" as the credits_balance label, and a negative-only payload still returns ok:true #1924 ("-5" credits label), claude fix(ai): claude quota extra-usage spend publishes negative amounts — "$-5.00 / $10.00", and a negative-only payload still returns ok:true #1919 ("$-5.00 / $10.00", negative-only payload mints the window); openrouter fix(ai): openrouter quota unlimited path publishes a negative spend — "$-5.00 spent" for usage_monthly below zero #1913 closed as the same defect.
• Pairs are never judged as pairs — groq fix(ai): groq quota accepts remaining above the limit — "150 / 100 requests remaining" publishes beside 0% used / 100% remaining #1897 ("150 / 100 requests remaining" beside 0% used / 100% remaining), opendesign fix(ai): opendesign quota parseCodingPlanWindows publishes out-of-range remaining raw — "-50 / 100 credits" at 100% used, "150 / 100 credits" at 0% used #1879 ("-50 / 100 credits" at 100% used); codex fix(ai): codex quota spend_control label publishes used/limit raw — "150 / 100 used" at a clamped 100%, "-5 / 100 used", "5 / 0 used" #1882 closed as the same split.
• A scaling input is trusted blindly — claude fix(ai): claude quota spend toAmount trusts the wire exponent — exponent 999 publishes "$0.00 / $0.00" for a real $5/$10 spend, exponent -2 inflates it 100x #1920: toAmount divides by 10 ** exponent with the wire exponent unvalidated (999 erases a real $5/$10 spend to "$0.00 / $0.00"; −2 inflates it 100×).
• Precision is discarded at publication — antigravity fix(ai): antigravity quota publishes integer-quantized percents — 99.9% used reads as 100% / 0% remaining, 0.1% used reads as 0% #1941: Math.round(remainingFraction * 100) at both conversion sites (99.9% used publishes as 100% / 0% remaining; 0.1% as 0%), while every sibling keeps the float percent and the CLI rounds only for display (fix(cli): quota renders unrounded percents — 33.33333333333333% used for a one-third-full window #1797).
• The shared layer was already rescued once — fix(ai): shared quota toUsageWindow derives remainingPercent above 100% — the percent cap floors at 0 but never caps at 100 #1904: toUsageWindow derived remainingPercent above 100%.

The precedents exist one provider at a time, exactly as the window rules did before #1794: meta parseBillingBanner returns null for minor < 0; opencode-go toMicroCents returns null for amount < 0; turso carries a private numNonNegative; command-code gates monthlyRemaining >= 0 (#1744) and clamps percent and label from one figure (#1821); deepseek filters total_balance > 0 (#1800). The shared layer (packages/ai/src/quota/utils.ts, read verbatim on current main) offers toNumber (negative included), clampPercent and formatMoney (formats a negative verbatim) — no amount reader, no pair check, no precision rule. Each open filing asks its fixer to re-derive the same dispositions alone, in one provider, again.

The contract

A figure that cannot exist is not a figure. For every number a quota parser publishes — percent, amount, balance, count, in a field or in a valueLabel — and for every wire scalar that scales one:

1. Impossible figures read as absent. Negative money / balance / spend publishes as absent, never as a formatted label (meta / opencode-go / turso / command-code precedent, generalised). Zero is a real figure and publishes unchanged.
2. A pair is judged as a pair. remaining ≤ limit etc.: individual well-formedness is not enough. The disposition of an impossible pair is whole-window and named per provider in the inventory — read-as-absent, or clamp-with-the-real-figure-annotated (fix(ai): Command Code quota monthly window vanishes when remaining credits exceed the hard-coded 10 included — an over-limit payload reads as 'could not be parsed' #1744's shape) — never split between percent (clamped) and label (raw). Extends design(ai): parse the window you were sent, or none — one window contract for the provider quota parsers #1794 rule 5 from derived fields to the raw pair.
3. Scaling inputs are figures too. An exponent / divisor / multiplier from the wire is validated against its closed range before it scales anything (money exponents: ISO 4217 0–3). Out of range reads the scaled figure as absent; sibling figures on the same window still publish.
4. Precision is part of the figure. A published percent keeps the wire's precision; rounding is a display act (CLI, fix(cli): quota renders unrounded percents — 33.33333333333333% used for a one-third-full window #1797), never a parser act.
5. A result whose only figure is impossible is no result. Refusing impossible figures that empties a result fires the provider's existing no-data contract (ok: false) — fix(ai): claude quota returns ok:true with empty windows for a 200 payload carrying no usable quota data #1915/fix(ai): codex quota windows keyed only by derived duration label — a missing or shared limit_window_seconds silently drops one window, and an empty window object mints a phantom all-null window #1762 extended from figure-less to impossible-only payloads.
6. Every figure path is pinned against this contract. One shared figure probe matrix (negative, zero control, impossible pair, out-of-range scaling input, sub-percent precision) per parser that publishes figures; the figure inventory rides the same types.ts table as the window inventory — not a second table to drift (docs(ai): quota window-contract inventory verdicts do not reflect the open known-lossy filings — six rows certify or omit parsers with live lossy issues, and turso's row has no verdict at all #1939 is the warning).

Named exception: turso's publish-truthfully over-100% disposition (#1743) stands — a provider's stated disposition governs its out-of-range figures, as under window rule 5. The contract forbids unstated and split dispositions, not stated ones.

Phases

• Phase 1 (FILED, new) — the contract stated in packages/ai/src/quota/types.ts beside the window contract; a figure section in the same parser inventory (figures published per provider + each figure's named disposition; known-lossy rows linked, not asserted); the shared figure probe matrix in packages/ai/test/quota.test.ts over the already-conforming parsers (meta parseBillingBanner, opencode-go toMicroCents + balance path, command-code clamp-both, turso numNonNegative path). Tests/docs only, no production behaviour changes. Filed as a sub-issue of this design issue.
• Phase 2 (ADOPTED) — the negative-figure family lands: fix(ai): deepseek quota publishes a negative balance — the no-positive fallback bypasses its own >0 filter, so a negative-only payload returns "$-5.00" with ok:true #1928 (deepseek), fix(ai): codex quota credits publishes a negative balance — "-5" as the credits_balance label, and a negative-only payload still returns ok:true #1924 (codex), fix(ai): claude quota extra-usage spend publishes negative amounts — "$-5.00 / $10.00", and a negative-only payload still returns ok:true #1919 (claude). Already filed, scoped, probe-verified; each keeps its own queue lifecycle, linked as sub-issues, not re-enqueued.
• Phase 3 (ADOPTED) — pairs, scaling inputs, precision land: fix(ai): groq quota accepts remaining above the limit — "150 / 100 requests remaining" publishes beside 0% used / 100% remaining #1897 (groq pair), fix(ai): opendesign quota parseCodingPlanWindows publishes out-of-range remaining raw — "-50 / 100 credits" at 100% used, "150 / 100 credits" at 0% used #1879 (opendesign pair), fix(ai): claude quota spend toAmount trusts the wire exponent — exponent 999 publishes "$0.00 / $0.00" for a real $5/$10 spend, exponent -2 inflates it 100x #1920 (claude exponent), fix(ai): antigravity quota publishes integer-quantized percents — 99.9% used reads as 100% / 0% remaining, 0.1% used reads as 0% #1941 (antigravity precision). Same terms as phase 2.
• Phase 4 (NOT FILED) — shared figure helpers in utils.ts; a scaling-input inventory across all 13 providers; a precision audit of every rounding site; the inventory-drift ratchet (shared question with design(ai): parse the window you were sent, or none — one window contract for the provider quota parsers #1794 phase 4 / docs(ai): quota window-contract inventory verdicts do not reflect the open known-lossy filings — six rows certify or omit parsers with live lossy issues, and turso's row has no verdict at all #1939). Open questions in the design doc.

Grounding

• packages/ai/src/quota/utils.ts — shared scalars only; no amount/pair/precision layer.
• packages/ai/src/quota/types.ts — window contract + parser inventory; balances scoped out by rule 4; inventory already drifting (docs(ai): quota window-contract inventory verdicts do not reflect the open known-lossy filings — six rows certify or omit parsers with live lossy issues, and turso's row has no verdict at all #1939).
• packages/ai/src/quota/providers/{deepseek,codex,claude,groq,opendesign,antigravity,meta,opencode-go,turso,command-code}.ts — the per-provider precedents and violations cited above.
• Related: design(ai): parse the window you were sent, or none — one window contract for the provider quota parsers #1794 (window contract — producer sibling, composed not duplicated), design(core): one quota signal, three consumers — shared QuotaSnapshot and weight-layer contract for #566/#567/#568 #587 (consumers), design(core): one numeric contract at the service boundary — shared normalisation primitives for limits, durations and timeouts #992 (core service-boundary numerics — different layer), docs(ai): quota window-contract inventory verdicts do not reflect the open known-lossy filings — six rows certify or omit parsers with live lossy issues, and turso's row has no verdict at all #1939 (inventory drift — cited, not adopted).

Acceptance criteria

• Phase 1 lands as filed: the figure contract is stated in packages/ai/src/quota/types.ts beside the window contract, the figure section rides the same types.ts inventory table as the window inventory (figures published per provider + each figure's named disposition), and the shared figure probe matrix (negative, zero control, impossible pair, out-of-range scaling input, sub-percent precision) runs in packages/ai/test/quota.test.ts over the already-conforming parsers. Tests/docs only — no production behaviour changes in phase 1.
• Phases 2 and 3 proceed only through their already-filed sub-issues (fix(ai): deepseek quota publishes a negative balance — the no-positive fallback bypasses its own >0 filter, so a negative-only payload returns "$-5.00" with ok:true #1928, fix(ai): codex quota credits publishes a negative balance — "-5" as the credits_balance label, and a negative-only payload still returns ok:true #1924, fix(ai): claude quota extra-usage spend publishes negative amounts — "$-5.00 / $10.00", and a negative-only payload still returns ok:true #1919; fix(ai): groq quota accepts remaining above the limit — "150 / 100 requests remaining" publishes beside 0% used / 100% remaining #1897, fix(ai): opendesign quota parseCodingPlanWindows publishes out-of-range remaining raw — "-50 / 100 credits" at 100% used, "150 / 100 credits" at 0% used #1879, fix(ai): claude quota spend toAmount trusts the wire exponent — exponent 999 publishes "$0.00 / $0.00" for a real $5/$10 spend, exponent -2 inflates it 100x #1920, fix(ai): antigravity quota publishes integer-quantized percents — 99.9% used reads as 100% / 0% remaining, 0.1% used reads as 0% #1941), each keeping its own queue lifecycle — no re-enqueueing from this design.
• No parser publishes an impossible figure (negative money/balance, impossible pair split between percent and label, out-of-range scaling input, parser-side percent rounding) once its adopting phase has landed, except under a provider's stated disposition (e.g. turso's publish-truthfully over-100% rule).