refactor(frontends): the frontend class owns registration, validation, worker shape, and endpoints

[ishandhanani]

Summary

Adding a frontend meant editing a Literal, an if-chain, a schema pairing map, four per-frontend schema validators, eleven frontend_type == "..." comparisons across the three backends, nine more in the telemetry target builder, a dozen in the benchmark stage, and three special cases inside the readiness loop. This PR makes the frontend class the owner of every one of those decisions, so a new router is one registered module. It is the groundwork #432 (vLLM MoRI-IO) will be rewritten onto.

Seven commits, each behavior-preserving except where noted:

1. Registry, required_backend, validate(config). @register_frontend("<type>") on each implementation, imported from the package __init__, replaces the FrontendType literal and the if-chain in get_frontend. Each frontend declares required_backend and its recipe rules in validate(config). SrtConfig has one _validate_frontend: type registered, backend pairing generic, the frontend's ValueError reported as a load-time ValidationError. The four per-frontend schema validators move into their classes with their messages unchanged.

2. Worker shape. worker_launch (dynamo or direct), worker_api_port(mode) (public or allocated), and expands_node_local_dp on the protocol. Backends resolve frontend_type through get_frontend and read those; no frontend-name comparison remains in backends/vllm.py, sglang.py, trtllm.py, or the nsys prefix builder.

3. Endpoint, metrics, and profiling ports. metrics_path, worker_metrics_port, worker_endpoint_port, profiling_control_port, profiling_control_is_leader_only, direct_endpoint_nodes, worker_ready_port. Tachometer scrape targets, the benchmark's logical endpoints and public API node, AIPerf metrics URLs, profiling control, and the sequential-start readiness port read them. Four behavior changes, each replacing a dead port the old per-site rules produced: the trtllm_serve aggregate endpoint is the public port it binds rather than its unbound http_port; the direct sglang nsys control port is the leader's public port rather than http_port; built-in AIPerf metrics for sglang-router target the worker leaders' HTTP ports rather than Dynamo system ports no sglang worker serves; direct frontends no longer return early from the metrics env, so KVBM and CPU power exporter URLs are appended for them too.

4. DynamicFrontend base. The counterpart of StaticRouterFrontend for frontends whose workers register themselves over a discovery plane. Dynamo is its only implementation; vLLM Router's ZMQ discovery mode stays a mode of a static router.

5. Readiness on the protocol. probe_ready(host, port, n_prefill, n_decode) performs one readiness check and returns a WorkerHealthResult; wait_for_model keeps only timing, abort, and logging, with no frontend names. core/health.py offers the three probe shapes: probe_json_health (a JSON count through parse_health), probe_http_ok (a bare 200, trtllm_serve), probe_direct_server (/health then /v1/models, direct vllm and sglang). health_expectations(config, processes) returns the counts in the frontend's own units; Dynamo's vLLM DP registration logic moves into frontends/dynamo.py, vLLM Router's expansion sum into frontends/vllm_router.py, and _get_health_expectations delegates with its signature unchanged. A router in a discovery mode overrides probe_ready and touches nothing else.

6. No del of unused arguments. Review comment: ruff's unused-argument rules are off here, so the 49 del name lines in the frontends were noise. Removed, with the rule noted in CLAUDE.md.

7. Protocol slimmed to what consumers call; implied_services and frontend_metrics_port. health_endpoint, parse_health, and get_frontend_args_list leave the protocol (the two bases keep them as their own hooks; the direct frontends drop never-called stubs; the dead check_trtllm_serve_health goes; one verbatim-args helper frontend_args_to_cli). implied_services(config) moves Dynamo's etcd/NATS rule from services/implicit.py onto DynamoFrontend, so a future registration-based frontend declares its own discovery plane. frontend_metrics_port(frontend_args) moves the SGLang gateway's separate Prometheus listener out of the telemetry stage. Two schema checks that re-derived frontend facts by name (profiler control on the leader only, Dynamo system ports) read profiling_control_is_leader_only and worker_launch. docs/architecture.md describes the protocol as it is now.

Validation

• Full suite: 2988 passed on Python 3.13 and 3.10 after the final commit (2972 on main plus 16 new tests across tests/test_frontends.py and tests/test_health.py: registry contents, registering a toy frontend, unknown type rejected at load, generic pairing per frontend, contract tests for the worker-shape and port members, the Dynamo sidecar case, the DynamicFrontend defaults, every frontend's probe against mocked HTTP, and the wait_for_model loop).
• srtctl dry-run for all 26 example recipes is byte-identical to main after normalizing generated timestamps, after every commit.

Review map

• frontends/base.py: the protocol members, the registry, logical_health_expectations, agg_leader_nodes.
• frontends/dynamic_frontend.py, frontends/static_router.py: the two bases.
• frontends/*.py: decorator, required_backend, validate, worker shape, port rules, probe, and expectations per class.
• core/health.py: wait_for_model reduced to the loop; the three probe helpers.
• core/schema.py: _validate_frontend replaces four validators; the nsys prefix reads worker_launch.
• backends/vllm.py, sglang.py, trtllm.py: name comparisons become attribute reads.
• core/telemetry.py, cli/mixins/benchmark_stage.py, cli/mixins/worker_stage.py: consumers read the frontend.
• CLAUDE.md: Frontends section and the mode-versus-type checklist describe the registry, the two bases, and the members.

The frontend-name checks left outside frontends/ are Dynamo-config and SGLang-gateway feature switches (sidecar, failover, and worker_selection validators, installs_dynamo, request tracing, slow_down, dry-run panels): each asks whether the recipe uses that product's feature block, not a topology or readiness question.