feat: define preference-driven recipe objective spec for offline tuning

Summary

Define a preference/objective contract for offline recipe tuning so users can express routing goals and constraints, and tuning agents can generate, rank, and evaluate candidate recipe patches against those goals before human/CI approval.

Parent roadmap: #2287 Related: #2340, #2366, #2367, #2341, #2333, #2378, #2238, #1512

Motivation

Current roadmap work already covers offline agentic config tuning, proposal contracts, threshold calibration, preset recipes, and decision-level eval. What is still under-specified is the objective layer: how a user or operator expresses preferences that determine which candidate recipe is better.

Without this contract, an agent can propose patches and eval harnesses can report metrics, but there is no shared scoring target for tradeoffs such as quality vs cost, latency vs grounding, privacy vs model capability, or stable routing vs exploration.

Scope

• Define a recipe_objective / tuning profile format for:
  • quality, cost, latency, safety, privacy, grounding, continuity/cache, and provider reliability goals;
  • hard constraints vs soft weights;
  • route-specific, decision-specific, or tenant-specific overrides;
  • model pool and capability assumptions;
  • accepted eval datasets, probe manifests, and replay sources;
  • acceptance gates and regression budgets.
• Define how objective specs consume:
  • decision-level eval results from #2333;
  • router replay and outcome records;
  • recipe probe manifests;
  • model pricing/capability metadata;
  • optional user or tenant preference labels.
• Define output scoring for candidate recipes:
  • candidate ranking and/or Pareto frontier;
  • expected metric deltas;
  • hard-constraint failures vs soft tradeoff explanations;
  • risk notes and blocked activation reasons;
  • compatibility with the #2366 config proposal/patch contract.
• Include at least one worked example for the balance recipe or a cost/accuracy preset from #2378.

Affected surfaces

• deploy/recipes/*.yaml
• deploy/recipes/*.dsl
• deploy/recipes/*.probes.yaml
• src/vllm-sr/cli/commands/recipe_learning.py
• tools/agent/scripts/tuning/
• future decision-eval artifacts from #2333
• future proposal artifacts from #2366

Non-goals

• Do not activate config changes on the request path.
• Do not replace #2340's offline tuning loop or #2366/#2367 proposal and approval flow.
• Do not train signal models or model-selection models in this issue.
• Do not make LLM-generated routing rules acceptable without eval evidence.
• Do not introduce a second recipe/config schema that cannot round-trip with current YAML/DSL recipes.

Acceptance criteria

• Preference/objective spec schema is documented.
• At least one maintained recipe or preset can declare a tuning objective.
• Candidate recipes can be scored against decision-level eval output.
• Reports distinguish hard-constraint failures from soft objective tradeoffs.
• The format can be embedded in or referenced by agentic config proposal artifacts.
• Validation guidance includes the relevant repo harness commands, for example:
  • make agent-report ENV=cpu CHANGED_FILES="..."
  • make agent-validate
  • targeted recipe/probe/eval commands once #2333/#2340 wiring exists.