design(core): one quota signal, three consumers — shared QuotaSnapshot and weight-layer contract for #566/#567/#568 #587

Decision needed (one line): Adopt the shared-contract design — one derived QuotaSnapshot signal, gates filter candidates before weighting, the burn-rate controller writes only through the existing tuner Adjustment channel — or keep #566/#567/#568 as three independent features with separate quota reads and config?

Summary

Three features filed the same day — #566 (quota-aware session placement), #567 (time-based weighting), #568 (native quota intelligence / burn-rate controller) — each presuppose a quota signal and a shared weight model that none of them defines, and each sketches a different config surface to do it. This design is the missing contract: (1) a QuotaSnapshot value derived from data the fork already owns (ModelPlan windows + windowReport() usage), with one staleness rule where unknown/stale is never treated as headroom; (2) a layering rule — gates (#566) filter candidates before weighting, weights rank survivors through the existing weightOf layers, the controller (#568) writes only expiring Adjustments like the tuner already does, and credential failover (#6) stays orthogonal inside an attempt; (3) per-layer weight attribution in the decision log so "why is this model ranked here?" is answerable for all three.

This extends — does not duplicate — the existing thread: #566, #567, #568, #6 stay as the implementation vehicles for phases 3–5. It also closes a roadmap gap: ROADMAP.md → "Routing, cost and plans" lists #6–#10 but has no row for #566/#567/#568. Full design doc: files/designs/opencode-quota-signal-routing.md in the keep-the-four-repos-healthy goal workspace (registered in files/potential-projects.md).

Current state (evidence)

• packages/core/src/model-route.ts → weightOf() already composes layers in order: scheduled WeightRules (time windows incl. from/until — most of Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567's mechanism exists) → user prefer overrides → learned tuner adjustments (non-fixed routes only) → quota demotion, a binary DEMOTED_FACTOR = 0.01 after quota errors (quotaCooldownMs: 900_000). Quota enters selection only as this reactive demotion.
• Quota knowledge is reporting-only: packages/core/src/model-plan.ts holds plans + QuotaWindows; packages/core/src/model-usage.ts → windowReport() derives percent / remaining / resetRule from recorded usage. The selection path never reads it.
• packages/core/src/model-route-tuning.ts → suggest() already produces expiring, id-replaced Adjustments (auto: ids) installed via setAdjustments/addAdjustment, gated by the route's autonomy level — the channel the controller should reuse.
• The decision log records final effective weights per candidate but not which layer produced them, so neither Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567's inspection acceptance nor Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568's audit acceptance can be met from the log today.
• The three issues' own words: Quota-aware session placement: filter by quota % and session type (root vs subsession) #566 "using the existing quota sources; a stale read… is treated as unknown"; Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567 "should share the weight model"; Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568 "should adjust the same weight model they use rather than inventing a parallel one" — followed by three incompatible config sketches (quota.gates.*, schedules:/boosts:, a controller ladder), none matching the code's actual config shapes.

Proposal (point of view)

• One snapshot, one staleness rule. QuotaSnapshot { planID, window, providerID, percent|null, remaining|null, resetAt|null, observedAt, stale }, derived purely from ModelPlan + windowReport() in v1 — no external polling. percent === null or stale ⇒ unknown: never headroom, never a wall; each consumer's configured fallback applies (gates default to admit = today's behaviour).
• Gates filter, weights rank. Quota-aware session placement: filter by quota % and session type (root vs subsession) #566's gates run as a candidate filter in nextTarget before weighting — a refusal, not a weight of 0 — so the decision log can say "refused" and sticky/continuity logic can't resurrect a gated target. The fleet rule (burn to 100%, then stop, never PAYG) is a refusal and is modelled as one.
• The controller is a second adjustment producer, beside the tuner, with its own id prefix, expiring adjustments, observe mode = compute + log without installing, act mode gated per-route by the existing autonomy levels. The more restrictive adjustment wins on collision; both are logged.
• Per-layer attribution in the decision detail: weight after each layer (base, scheduled, prefer, adjustment, demotion) plus gate verdicts — one inspection feature serving Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567 and Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568.
• feat(routing): automatic multi-credential failover on 429 quota exhaustion via credential.activate #6 stays orthogonal: credential failover inside an attempt on a selected target; it neither reads snapshots nor writes weights.
• Alternatives that lose, with reasons, are in the design doc: per-feature quota reads/config; external polling first; gates-as-weights; a new controller weight layer above weightOf.

Phased breakdown

1. Phase 1 — QuotaSnapshot derivation + staleness contract. Pure module over ModelPlan + windowReport() data; unknown/stale rules; unit tests (missing limit, missing windowHours, stale observation, threshold boundaries). No selection behaviour change. (Filed as a sub-issue of this design issue and enqueued.)
2. Phase 2 — Per-layer weight attribution in the decision log. Traced weight computation; traced weights must equal weightOf weights; surfaced via existing route-review tooling. No behaviour change. (Filed as a sub-issue of this design issue and enqueued.)
3. Phase 3 — Quota gates on the snapshot. The existing Quota-aware session placement: filter by quota % and session type (root vs subsession) #566, re-scoped onto this contract once the decision lands. (Not re-filed — Quota-aware session placement: filter by quota % and session type (root vs subsession) #566 is the vehicle.)
4. Phase 4 — Controller as adjustment producer. The existing Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568; its telemetry acceptance is narrowed by Phase 1. (Not re-filed.)
5. Phase 5 — Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567 close-out. Verify WeightRule windows/boosts against Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567's acceptance; inspection surface on Phase 2's attribution; retire its separate config sketch. (Not re-filed.)

Open questions (in the design doc, deliberately not filed as issues)

• Which reset rules can yield a concrete resetAt, and does the controller need it, or is percent + remaining enough?
• Per-credential quota dimension once feat(routing): automatic multi-credential failover on 429 quota exhaustion via credential.activate #6 lands, or is provider-level percent the right gate granularity?
• Snapshot max-age default (the wider fleet uses a ≤60-minute quota read for placement decisions).

Non-goals

• No PAYG routing, ever (inherited from Quota-aware session placement: filter by quota % and session type (root vs subsession) #566/Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568 and the fleet pool rule).
• No change to ModelRouteSchedule semantics.
• No cross-repo quota sync with developing-today/code's provider-quota registry in v1.

Related

• Quota-aware session placement: filter by quota % and session type (root vs subsession) #566, Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567, Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568, feat(routing): automatic multi-credential failover on 429 quota exhaustion via credential.activate #6 (the features this contract serves), fix(core): route_usage silently omits plan quota windows that have no windowHours — monthly/reset-rule windows never appear #550 (windowReport omits windows without windowHours — snapshot must surface those as unknown)
• Files: packages/core/src/model-route.ts (weightOf, nextTarget), packages/core/src/model-route-tuning.ts, packages/core/src/model-plan.ts, packages/core/src/model-usage.ts (windowReport), ROADMAP.md

Acceptance criteria

• The decision in the first line is recorded on this issue (adopt the shared contract, or keep the three features independent), with the decider named.
• If adopted: Phases 1–2 land as their sub-issues specify, and Quota-aware session placement: filter by quota % and session type (root vs subsession) #566/Time-based model/provider weighting: peak/off-peak profiles and temporary priority windows #567/Native quota intelligence: burn-rate estimation and dynamic reprioritization to consume quota before reset #568 are re-scoped onto the contract (snapshot + layering) in their bodies.
• If not adopted: the rationale is recorded here and the three issues' "shared weight model" expectations are removed or replaced, so the thread does not stay dangling.
• No code changes land under this design issue itself.