[Deep-Sixed]

Summary

Phase 1 of Jev routing. This adds a jev-router alias mode: OpenRouter's hosted Jev Router becomes one model-selection strategy, alongside dedicated paths and Fusion. Cerberus keeps the policy and decides what may run. Jev decides which of those should run for each request.

cerberus/auto:
  mode: jev-router
  candidates:                       # the pool; no preference order
    - { provider: openrouter, credential: primary, model: anthropic/claude-sonnet }
    - { provider: openrouter, credential: primary, model: google/gemini-pro }
  jev_router:
    timeout_seconds: 120
    allow_paid_pool: true

Cerberus filters first; Jev only sees what survives

• Validation (registry/schema.py):
  • Every candidate is an exact registry slug, and the whole pool uses one OpenRouter credential.
  • Refused: wildcard/~family patterns (they could match models the registry never listed), duplicates, per-candidate reasoning_effort / chat_template_kwargs (Jev chooses reasoning effort per request), and allow_paid_fallback.
  • A paid pool member requires allow_paid_pool.
• router/pool.py (new) is one filter used by dispatch and /admin/routes. It applies cost first, then health → cooldown → credential, the same order the failover loop uses. It doesn't depend on Jev, so the planned native Jev strategy can reuse it.
• Only the filtered pool is sent, as the jev-router plugin's models list. An empty pool is never sent: OpenRouter treats a list that matches nothing as no list at all and routes over its whole pool, so Cerberus answers 503 instead.

models_ignored and other out-of-pool responses are rejected

Every call sends X-OpenRouter-Metadata: enabled. A response is accepted only when all of these hold:

• the jev-router pipeline stage is present
• it reports no list_fallback
• the served model and every resolved_models entry are in the pool that was sent (a slug also matches its -YYYYMMDD revisions, as the plugin documents)

Any other response is withheld with 502 and recorded as out_of_policy. Because the call has already been billed, its usage and reported cost are still recorded. openrouter_metadata is stripped from the payload. The decision is reported in the cerberus envelope and in telemetry instead.

Callers can't influence routing

jev-router allows the shared CALLER_FIELDS from Deep-Sixed/Cerberus#23, minus reasoning_effort / chat_template_kwargs, plus function tools only.

• Dispatch silently drops unknown fields. jev-router instead refuses them with a 400 before any upstream call. That covers models, route, plugins, preset, provider, server tools (openrouter:*, web_search, …), reasoning_effort / reasoning, and any field not on the list.
• The 400 is recorded as an invalid_request routing event.
• For that reason jev-router, like fusion, is exempt from Forward only standard chat fields and function tools upstream #23's app-level server-tool check.

Telemetry and console

• Telemetry schema 6: a jev_router record (pool sent, returned model, router decision, violation) and three new outcomes: out_of_policy, jev_router_unavailable, invalid_request.
• /admin/routes and the console show the alias as a pool (each member eligible or excluded, never standby), with readiness and decision evidence.
• The control plane stores binding_type = 'jev-router' and route_members rows with role pool. No migration is needed.

Not in this PR

• Streaming. The decision has to be checked before any of the answer is returned.
• A per-request cost ceiling. Cerberus doesn't hold model prices, and a ceiling checked after a routed call is too late.
• Phase 2: native Jev, where Cerberus asks Jev's decision API to choose among every eligible backend (local, Cloudflare, OpenRouter, …) and runs the winner itself.

Test plan

• ./scripts/ci.sh on the branch with Forward only standard chat fields and function tools upstream #23 merged in: ruff clean, 376 passed.
• Mutation check: disabling the pool check and the caller-field gate fails 21 of the new dispatch tests.
• uv build --no-build-isolation; the wheel includes cerberus/jev_router.
• node --check src/cerberus/ui/static/app.js
• python scripts/check-public-history.py: 0 findings.
• Live probe against OpenRouter, to confirm the openrouter_metadata stage shape matches the documentation. If it differs, every jev-router response is withheld as decision_unverifiable; that is the safe failure.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P4Nm4MVSMmG6JyZi8WumtK