docs(research): provider quota headroom and multi-account failover analysis (#15021)

[mrveiss]

Summary

Research doc backing umbrella #15021: an analysis of the multi-provider AI quota-manager pattern as implemented by an external reference implementation, followed by an audit of AutoBot's LLM provider resilience against it.

The external product and vendor are deliberately not named; what is analysed is the pattern.

Docs-only — no code changes.

Changes

• docs/research/provider-quota-headroom-and-account-pooling.md (new)

Key finding

GET /costs/quota-windows (llc/api/costs.py:209-244) returns provider quota-window structure with no values; its docstring says they "are populated by the quota monitor (phase 3)". Grep for that monitor returns two hits — the comment and its generated OpenAPI copy. It was declared and never built. Umbrella #15021 finishes it.

The audit also confirms AutoBot holds exactly one credential per provider per tenant (provider_auth.py:146, singular routes at api/provider_auth.py:588,620, zero hits for any account-pooling grep).

Testing

Docs-only. All AutoBot code citations verified by reading the cited files at the cited lines.

Related

• Umbrella: Umbrella: provider quota headroom + multi-account failover — finish the declared-but-unbuilt quota monitor #15021
• Children: llm: degradation store cannot distinguish a dead credential from a transient failure — dead tokens retry every TTL forever #15022, llm: harvest provider rate-limit response headers into a cross-worker quota headroom store (the missing quota monitor) #15026, llc/api: /costs/quota-windows returns structure with no values — populate it and add typed metric presentation #15027, llm: route on observed headroom before dispatch instead of on a 429 after it; reconcile guessed RPM buckets with observed limits #15028, llm-auth: one credential per provider per tenant — add a multi-account credential pool with headroom-based selection #15029, frontend: surface per-account quota headroom and provider lifecycle state in the provider view #15030
• Unrelated discovery filed during the audit: frontend(i18n): ProviderOAuthConnect.vue has hardcoded user-facing strings — no $t(), no useI18n #15031
• Supersedes docs(research): superseded by #15033 #15032 (same content, branch renamed)

[mrveiss]

Closing unmerged by decision — the decision-bearing content was absorbed into #15021 (evidence table, design constraints, deliberately-not-adopted table) and into the six child issues' scope sections. Merging would leave a dated comparison snapshot in the repo with no consumer.

The analysis is preserved on branch research-provider-quota-headroom if it is ever wanted back.