feat(routes): experimental.model_route_settings — route machinery constants as config, defaulted to current values #1141

Drew's directive (2026-10-31): "make constants into experimental config defaulted to current values."

Problem

The model-route machinery's tuning constants are hardcoded in packages/core/src/model-route.ts. The per-route health block covers only the two bench bases (60s failure / 900s quota). Everything else — the bench ladder's shape, quota demotion, the quota gate, escalation, the network-suspect heuristic, continuity hedging, the user-preference default — is a literal or an entry in DEFAULT_SETTINGS, for which a code-level ModelRoute.configure() hook exists but no config key feeds it (grep-verified: configure() is called only from tests). Operators cannot tune any of it without a code change and a rebuild.

Constants inventory (all in packages/core/src/model-route.ts unless noted)

New config home for every row: experimental.model_route_settings, grouped so the block can later move under experimental.routes.settings with a mechanical path change when the staged nesting (#1140) lands.

bench — the cooldown ladder

demotion — quota-error demotion

quotaGate — exhaustion gates from quota snapshots / attempt reports

escalation — racing the next target after give-ups

network — network-suspect forgiveness / provider-wide demotion

continuity — hedging back to a failover origin

overrides — user preference default

Deliberately left hardcoded

• Backoff exponent cap (30) in bench() — an arithmetic overflow guard, not a knob: 2^30 × 1ms ≈ 12.4 days already exceeds the 24h bench cap, so the cap always binds first.
• State memory bounds — HEALTH_LIMIT 2_000, SESSION_LIMIT 5_000, CONTINUITY_LIMIT 5_000: LRU caps on process-local maps. Resource-safety invariants, not routing policy.
• Event buffer caps — recentFailures ring at 200, quota-event history at 50 (recordQuota): bounded-memory invariants sized as headroom over the thresholds they serve. The schema therefore caps demotion.after at 50, so a configured threshold can never exceed the retained history.
• Usage-accounting internals — BUCKET_MS 6_000, DAY_MS 86_400_000, the 60s last-minute usage window: ledger bucketing granularity/retention, not failover policy.
• Relational clamps in policy() (slowThreshold ≤ sampleWindow; sampleWindow ≤ 50 mirrors the schema's SampleCount) — consistency clamps tied to the schema, not standalone values.

Same property, noted as follow-up (out of scope here): model-route-limits.ts (MAX_WINDOW_MS 24h, UNKNOWN_RESET_MS 60s — burst rate-limit holds) and model-route-tuning.ts (MAX_QUOTA_RESET_MS, which mirrors quotaGate.maxMs and should stay in step with it).

Design

• Schema: a Settings class in packages/schema/src/config/model-routes.ts with grouped sub-objects (bench / demotion / quotaGate / escalation / network / continuity / overrides), every field optional and annotated with its default; registered as experimental.model_route_settings in packages/schema/src/config/experimental.ts. The grouped shape survives either schema outcome: it works flat today, parallel to model_routes, and moves under experimental.routes.settings mechanically when config: nest routing config under experimental.routes (models, providers, windows, schedules, tuning, log, settings) with a normalize compat shim for the flat keys #1140 lands.
• Validation rejects nonsense: durations are positive ints bounded at 90 days; bench.multiplier ≥ 1 (below 1 successive benches would shrink); demotion.factor in (0, 1] (0 would zero a weight; above 1 a quota error would promote); demotion.after ≤ 50 (retained-history cap, above); network.providers ≥ 2 (1 would forgive every lone failure as a network fault); counts are positive ints.
• Wiring: the model-routes config plugin registers a lazy settings reader on ModelRoute (the ModelRouteLog.onCaptureErrorBodies precedent), so config reloads are honored without a restart. demotion.after / demotion.windowMs and escalation.enabled / afterGiveUps feed the pre-existing Settings / configure() store; the rest feed a new Constants store with configureConstants() / currentConstants() mirroring configure() / currentSettings().
• Precedence: compiled defaults ← programmatic configure() / configureConstants() ← config. Per-route health bases still override locally for their route; the bench caps (now bench.cooldownCapMs / bench.quotaCooldownCapMs) bound those local values exactly as the hardcoded caps do today.

Acceptance

• With no model_route_settings in config, behavior is bit-for-bit current behavior: the existing model-route test family passes unchanged (no edits to existing expectations), and new tests assert the resolved defaults equal the current constant values.
• New tests show config overrides change behavior: demotion factor, bench max cap, quota-gate fallback (plus defaults + validation coverage).
• Typecheck clean; the routing skill doc (routing-config.md) documents the block.

Acceptance criteria

• A new experimental.model_route_settings config block feeds every inventoried constant in packages/core/src/model-route.ts, grouped as specified in the body.
• With no config set, behavior is byte-for-byte the current defaults (existing route tests pass unmodified).
• Setting a value in config observably changes the corresponding machinery constant without a code change.