feat: [AMD Support via SemiAnalysis][2/4] vLLM MoRI-IO integration

[cquil11]

Summary

Integrate native vLLM Router with MoRI-IO prefill/decode workers. Static router registration and NIXL port handling do not describe MoRI's ZMQ discovery path; this PR supplies the connector-specific launch, port, and readiness contract for it on the seams main now has: a connector table row on the vLLM backend, discovery hooks on the vLLM Router frontend, and per-process listeners from the port allocator.

Stacked on #431, which combines AMD hardware enablement and required cluster runtime. #433 follows this PR; ATOM uses Mooncake and has no engine dependency on MoRI.

Review map

• backends/vllm.py: moriio is a KVConnector row with discovery=True and a mode-dependent role (the row type, the connector_for_mode resolver, and the discovery seam landed on main in refactor(frontends,vllm): readiness probes see the recipe; one connector resolver; discovery seam on static routers #491, so no connector name is compared in a branch here). kv_transfer_config(mode, process, runtime) builds the worker JSON; the topology arguments are optional and only a discovery row reads them. For a discovery connector the extra config carries proxy_ip (head node), proxy_ping_port, http_port, host_ip (the worker's own routable IP), handshake_port, notify_port, read_mode: the keys moriio_common.py reads (vllm-project/vllm 9679173788). Upstream's fixed defaults of 6301 and 61005 collide as soon as two workers share a node, so the allocator hands each worker a handshake port and a notify block of one port per local rank (upstream adds the DP and TP rank to the base); a worker built without them is refused. Such a worker gets no VLLM_PORT scan range because MoRI-IO opens listeners inside TP children that inherit it.
• frontends/vllm_router.py, ports.py: in discovery mode the vLLM Router adds --kv-connector <name> --vllm-discovery-address 0.0.0.0:36367 (RouterArgs in vllm-project/router) and validates the discovery rules (both roles on the connector, a P/D topology, one router on the head node). Readiness is the Router's own /health, which answers 503 until a prefill and a decode have registered (vllm-project/router 43140bc8e2, VllmPDRouter::health); the probe reads the recipe refactor(frontends,vllm): readiness probes see the recipe; one connector resolver; discovery seam on static routers #491 hands it, so core/health.py has no per-frontend branch and no completions POST. The probe_ready docstring records why /health and not /workers, and what the upstream fix would be.
• core/schema.py: refuses a discovery connector with any frontend other than vllm-router; the Router's own rules live in its validate.
• core/topology.py: Process.moriio_handshake_port and moriio_notify_port.
• Docs: docs/vllm-router.md gains a MoRI-IO discovery section with the full contract table; config-reference.md points at it; the port tables in CLAUDE.md and docs/architecture.md list the two kinds. examples/vllm/vllm-router-moriio-disagg.yaml (colocated P/D) is in the examples matrix and in every example-driven test.
• Tests: worker JSON against the realized topology, refusal without listeners, colocated listener allocation, the role override, the discovery command, the bootstrap port, the /health probe, and the recipe rules.

All four fork PRs target upstream main and are manually stacked: #431 → #432 → #433 → #476. Each later branch includes the preceding layers; merge in order and rebase the remaining PRs.

Review only this layer.

[ishandhanani]

Merged the updated #431 head into this branch and rebuilt the MoRI-IO layer on what main now has (#487 frontend protocol, #489 ports and backend protocol). Same feature, same recipe surface (engine.connector: moriio); the implementation moved onto the existing seams. I updated the review map in the description to match. What changed and why, in review-finding order:

1. Readiness is the Router's own /health, not a completions POST. Since vllm-project/router 43140bc8e2 VllmPDRouter::health answers 503 Waiting for discovered workers until a prefill and a decode have registered, then 200. VLLMRouterFrontend.probe_ready polls it in discovery mode; probe_ready now takes the recipe on every frontend so the frontend decides, and core/health.py has no frontend_type == "vllm-router" branch and no model name to thread through.
2. Handshake and notify ports come from the allocator. Upstream defaults every worker to 6301 and 61005, which collide the moment two workers share a node (the repo's own colocated P/D layout). Each discovery worker now gets moriio_handshake_port and a moriio_notify_port block of one port per local rank (upstream adds the DP and TP rank to the base, moriio_common.py 9679173788), plus host_ip set to its own routable IP instead of upstream's interface guess. A worker built without these is refused rather than defaulted.
3. One resolver for the connector. connector_for_mode(mode) covers engine.connector and the roles.<role>.args.connector override; uses_moriio() read only the engine-level field. discovers_workers() is built on it, and validate requires both roles to agree.
4. The name lives in the table. _CONNECTOR_MAP rows are KVConnector with a discovery attribute; moriio is a row, and nothing compares the string "moriio" in a branch. kv_transfer_config builds the JSON from the row and the topology.
5. Validation moved to the frontend. The P/D-only, single-router, head-placement rules are in VLLMRouterFrontend.validate; the schema only refuses a discovery connector with any other frontend.

Also: examples/vllm/vllm-router-moriio-disagg.yaml, a MoRI-IO section in docs/vllm-router.md with the contract table, and the duplicate vllm-router heading in config-reference.md folded into the existing one. Full suite on Python 3.13 and 3.10, and srtctl dry-run on all 26 baseline example recipes is unchanged from #431.

One thing I could not verify here: the exact vllm-router version your container ships. Discovery-aware /health needs 43140bc8e2 (2026-08-10) or later; with an older router the readiness gate would time out instead of passing early, which is the safe failure.

[ishandhanani]

Restacked on #491 (merged) through the updated #431 head. The seams this PR used to carry are now on main, so the layer over #431 dropped from 26 files (+762/-74) to 19 files (+614/-28), and its source diff is only the feature: the moriio row and its topology JSON in backends/vllm.py, the two port kinds and Process fields, the Router's discovery command, validation and /health probe in frontends/vllm_router.py, and the schema guard. Everything else is docs, the example recipe, and tests.

One API note from the restack: kv_transfer_config(mode, process=None, runtime=None) keeps #491's one-argument form; only a discovery row reads the topology arguments and refuses to run without them.

Full suite on Python 3.13 and 3.10; srtctl dry-run on all 26 baseline example recipes is unchanged from #431. Description updated to match.