research: orchestrate closed-loop self-adaptation across WRP knobs

Motivation

Research a safe outer loop that evaluates and recommends changes across Workload–Router–Pool (WRP) knobs without collapsing them into one unauditable online controller.

Audited upstream baseline (2026-07-15)

• Router Learning online adaptation can change the selected model only inside the current candidate set and protection envelope.
• The accepted design places broader recipe changes in an offline, reviewable recipe-learning loop; the end-to-end proposal/approval implementation remains tracked by #2340/#2366/#2367/#2393.
• FleetSim evaluates fleet/pool/routing configurations offline.
• Current main has no production meta-controller coordinating router recipes, workload shaping, and downstream pool actuation.
• Router Memory and generic model-selection packages are not the controller state/experience store.

Proposed architecture

Use an offline/nearline recommender with separate actors:

1. Router Replay and downstream acknowledgements produce versioned, content-minimized observations.
2. An evaluator builds a reproducible snapshot and compares current policy with candidates.
3. Router candidates go through the offline recipe proposal/approval path tracked by #2340/#2366/#2367/#2393; online Router Learning protection remains a separate request-time boundary.
4. LB/operator candidates go through the downstream control plane's own validation, canary, and rollback.
5. A coordinator records dependencies and ordering, but cannot bypass either actor's hard gates.
6. Online per-query Router Learning remains narrow and independently disableable.

Research scope

1. Define the state/action/outcome schema and exact ownership of each WRP knob.
2. Define multi-objective constraints: task quality/safety/SLO first; cost/energy/throughput only inside the feasible set.
3. Establish independent single-knob baselines before joint recommendations.
4. Add causal/coverage warnings; avoid attributing downstream outcomes to concurrent untracked changes.
5. Use FleetSim/replay for counterfactual screening, then shadow and staged canaries.
6. Add cooldown, change budget, dependency ordering, drift detection, rollback, and human/CI approval.
7. Separate recommendation, approval, actuation acknowledgement, and measured outcome.
8. Specify recovery after stale telemetry, partial failure, restart, or disagreement between actors.

Boundaries

• No monolithic controller on the ext_proc hot path.
• No online recipe/taxonomy/tool-policy or pool-capacity mutation through Router Learning.
• Authorization, safety, residency, and SLO constraints are non-negotiable.
• The semantic router does not directly mutate serving pools.
• Missing/low-coverage evidence yields no recommendation.
• Every actor can disable or roll back its part independently.

Acceptance criteria

• Typed schema and ownership matrix cover all inputs/actions/outcomes.
• Single-knob baselines and ablations precede joint optimization claims.
• Candidate evaluation is reproducible and reports uncertainty/coverage.
• Router and pool changes have separate approval, canary, acknowledgement, and rollback.
• Change budgets/cooldowns prevent oscillation and simultaneous unsafe mutations.
• Replay can reconstruct the full recommendation-to-outcome chain.
• Failure-injection tests cover stale data, partial actuation, conflicting recommendations, and recovery.
• Automatic operation, if ever proposed, is a separate explicitly reviewed milestone.

Likely change surfaces

src/semantic-router/pkg/routerreplay/, src/semantic-router/pkg/routerruntime/, Router Learning offline recipe tooling, src/fleet-sim/fleet_sim/optimizer/, deployment LB/operator APIs, observability/dashboard, docs, and tests.

Related: #2238, #2340, #2359, #2513, #2546, #2550, #2557, #2558.

Validation entrypoint

make agent-report ENV=cpu CHANGED_FILES="<space-separated changed files>"

Follow the reported gates and affected E2E profiles.