feat(routes): round-robin weights as priority tiers — rotate within a tier, fall through when it is exhausted #1122

Ruling

Drew (2026-10-31 ~20:19 CDT), on route pool selection:

allow round robin to accept weight but instead of all of them even or all of them by weight, evenly go through each priority so lowest weight even until all fail then second lowest evenly and so on

Semantics to implement

In a round-robin pool, weights stop being proportional shares and become priority tiers:

• Targets with equal effective weight form one tier. Within the active tier, selection rotates evenly across dispatches (the existing per-session draw + stickiness, restricted to the tier).
• Selection falls through to the next tier only when every member of the current tier has failed or is unavailable for that dispatch's candidate walk (not ready, already tried, gate-closed, cooling, quota-gated — the existing eligibility rules decide membership as today).
• All-equal weights (or no weights; unset weight still defaults to 1) collapse to a single tier, which is exactly today's plain even round-robin. Unweighted pools do not change behavior.
• ordered mode is untouched.

Tier order: higher weight = earlier tier (interpretation, flagged)

Drew's wording says "lowest weight" first, but the fleet's pools already use weight as preference, larger = preferred:

• the GPT pools put alternate at weight 2 over main at 1 precisely so alternate burns first;
• luna-plan puts the Go leaves at 3/2 above the rest;
• the DeepSeek plan pool uses a weight-100 guard to keep plan doors ahead of PAYG.

A literal lowest-first reading would invert every one of those pools. This issue therefore implements descending order (highest weight is the first tier). If Drew reverses the call, the change is the tier sort comparator and nothing else.

The tier key is the target's effective pre-demotion weight: configured pool weight after scheduled rules, user preferences, and learned adjustments — the same layers tracedWeightOf already computes, stopping before the demotion layer.

Interaction with quota demotion

Demotion today scales the effective weight by 0.01, which under tiering would smear a demoted heavyweight into the middle tiers (100 x 0.01 = 1 ties it with nominal 1s). Rule instead:

• While demoted (>= quota.demoteAfter quota errors inside quota.windowMs, per target or per serving credential as today), a leaf sits in a demoted tier below every non-demoted tier, whatever its configured weight. Demoted leaves still order among themselves by weight, and they still serve as last resort when nothing else is left.
• A nested group counts as demoted only when every currently eligible leaf under it is demoted; a mixed group stays in its nominal tier and its own walk applies the same rule one level down.
• The 0.01 factor itself is unchanged for ordered and weighted modes, whose ranking keeps using the final effective weight exactly as today.

weighted mode: left as-is

weighted remains the proportional mode (random draw by ratio) for pools that genuinely want shares. The ruling redefines round-robin only; removing the only proportional mode is not part of it.

Acceptance criteria

Tests in the model-route suite cover at least:

1. Single-tier pools rotate evenly, as today.
2. Two-tier strict fall-through: the second tier is never drawn while any first-tier member is ready; it engages once every first-tier member has failed / left the candidate set, within a single dispatch walk and across dispatches.
3. Within-tier rotation persists across dispatches (successive sessions cycle through the tier, not the pool).
4. An unset weight lands in the same tier as weight 1.
5. A quota-demoted leaf sorts below all non-demoted tiers regardless of nominal weight, and serves again as last resort.
6. A nested route reference participates as a tier member with its group weight.

No config changes; selection logic and its tests only.