Router Learning adaptation, protection, experience, and recipe-learning roadmap

Purpose

Track the remaining Router Learning work against the public contract that exists on current main.

Current public contract

• Enablement: global.router.learning.enabled.
• Day-zero online strategy: adaptation.strategy: routing_sampling.
• Safety envelope: protection.
• Per-decision online actions: decision adaptations.
• Experience source: Router Replay plus typed learning outcomes.
• Broader recipe changes: offline recipe learning, validated and applied through the existing configuration workflow.

The canonical design is website/docs/proposals/router-learning-memory-and-adaptations.md.

The day-zero online path and typed outcome ingestion exist on current main. Durable/distributed experience, seed-pack materialization, offline recipe proposal/approval, and broader strategy work remain follow-ups; this issue must not imply those loops are already production-complete.

Architectural boundary

• Online learning may adjust the selected model only inside the already validated candidate set and protection envelope.
• Recipe/taxonomy/signal/policy changes remain offline, reviewable, and reversible.
• Router Memory (pkg/memory) is prompt-visible user/conversation memory; it is not the Router Learning experience store.
• Legacy lookup_tables and method-keyed bandit/elo/session_aware public APIs are not part of the current contract and are rejected by validation.
• The hot path must not depend on synchronous durable storage.

Child status audited on 2026-07-15

• #2239 — harden the typed Router Learning runtime and extension contract
• #2240 — materialize/version experience and optional offline seed-pack artifacts
• #2241 — extend typed adaptation evidence/composition without legacy public methods
• #2242 — finish migration cleanup and reject legacy public learning config
• #2243 — durable/cross-replica experience semantics
• #2244 — closed
• #2237 and #2258 — merged implementation PRs, not open child issues

Newly linked follow-up opportunities

• #2541 — offline RL for session-level objectives, evaluated from Router Replay
• #2542 — materialize HaluGate outcomes into model/domain reputation
• #2544 — normalize failure classes into Router Learning experience
• #2545 — learn tool/model recommendations from tool outcomes
• #2548 — evaluate privacy-bounded caller risk signals
• #2559 — coordinate offline recommendations across router and downstream pool controls
• #2393 — define a preference-driven recipe objective contract

Definition of done

• Public configuration remains clean and validated.
• Outcome schemas are typed, versioned, privacy-bounded, and replayable.
• Online changes are bounded by protection and emit deterministic reasons.
• Offline recipe candidates have baseline comparison, approval, rollback, and provenance.
• Restart and multi-replica semantics are explicit.
• Router Replay can reconstruct the state/action/outcome path; new derived learning projections are content-minimized by default, while existing Replay content retention remains separately configured.
• Maintained examples, docs, metrics, and E2E tests cover the supported contract.

Likely change surfaces

src/semantic-router/pkg/routerruntime/, src/semantic-router/pkg/routerreplay/, src/semantic-router/pkg/extproc/, src/semantic-router/pkg/config/, src/vllm-sr/cli/, src/fleet-sim/, maintained examples, documentation, and tests.

Implementations must begin with make agent-report ENV=cpu CHANGED_FILES="..." and follow the reported gates.