[Platform] Thread vendor KV pool classes through the in-tree builders; add PlatformCapabilities

[alexnails]

folding in musa, npu, and oot kv contract

---

CI States

Latest PR Test (Base): ✅ Run #37523252004
Latest PR Test (Extra): ✅ Run #37523251744
Latest PR Test (AMD ROCm 10): ❌ Run #37523251848

[alexnails]

Design review of the seam itself — findings and what changed

Two follow-up commits on this PR. Recording the reasoning so reviewers can push back on the shape, not just the diff.

The concern that drove this

KVPoolRequest is bad integration point. Its shape fields (size, dtype, head_num, layer_num) describe what the pool must hold — legitimately the vendor's problem. But layout, attention_backend, is_hybrid_swa, post_capture_active describe how the configurator decided, i.e. promises about our own selector. Two bugs found in review were symptoms rather than independent defects:

• layout was reported as page_major for MLA/DSA, where the in-tree path never builds page-major.
• size was the combined budget for hybrid-SWA, where in-tree sizes the full pool from full_max_total_num_tokens.

Same failure both times: the struct claimed to mirror a decision it was not mirroring. "Adding a field never breaks a platform that ignores it" is true for additive change and irrelevant here — a field that lies is worse than a missing field, because a conscientious vendor honors it.

What is fixed

• Closed domains. kind, layout, and the new quant_scheme are Literals. Exhaustive matching now gets a signal when a member is added, instead of an else arm serving a new family as an old one.
• MiniMax-sparse no longer arrives as "mha". The dispatcher routes it to MiniMaxSparseKVPool after the seam, so a platform answering the "mha" request built something minimax_sparse_backend.py then rejects with an isinstance assert — and the request gave it no way to decline. Now "mha_sparse_index". Deprecated class hooks still map it to get_mha_kv_pool_cls, so migrated and unmigrated OOT platforms are unchanged.
• quant_scheme makes fp4/mxfp8 explicit; mxfp8 was only reachable by string-matching kv_cache_dtype_str.
• Paths with no seam now fail loud for OOT. Unified memory returns before _build_token_to_kv_pool entirely; DSV4 has a dedicated builder ahead of the seam. Both silently built CUDA-assuming pools for a device main does not know about. reject_out_of_tree_path names the subsystem — distinct from require_out_of_tree_impl because there is no hook to point at.
• allocator/hisparse.py constructed PagedTokenToKVPoolAllocator directly at three sites. Same bug as Fix SWA allocator factory selection for OOT platforms #27679, one file over from the fix.
• Hybrid-SWA documented as not-yet-buildable. is_hybrid_swa/full_size/swa_size give the budget but not the sliding/full layer-id split a composite needs.
• Docs. plugin.mdx still documented the class getters as raise NotImplementedError and never mentioned the seam.

The bigger issue this PR does not fix

The real contract is wider than KVCache. The ABC declares four abstract methods, but in-tree callers reach for concrete attributes and gate on isinstance against concrete classes:

• disaggregation/utils.py:1206,1218 hardcodes NPUMLATokenToKVPool in otherwise generic code — the precedent a new vendor copies is one core PR per vendor per feature.
• 58 isinstance gates on concrete pool classes across srt/.
• 7 of 8 attention backends check concrete SWAKVPool; only triton_backend.py uses BaseSWAKVPool. A vendor's own SWA composite is treated as a flat pool.

So this PR decouples the construction side and leaves the consumption side untouched. Honest framing: it moves ctor-kwarg coupling (fails at startup, TypeError, loud) to method/attribute/identity coupling (fails at first PD transfer or hicache attach, late). Better failure timing, same class of problem. build_kv_pool's docstring now says to subclass the concrete pools rather than implement KVCache, so vendors do not discover this by breakage.

Proposed follow-ups (stacked, alongside the NPU PR)

1. Dogfood the seam — factor the in-tree dispatcher into build_in_tree_kv_pool(request) and have in-tree platforms consume the same request. Nothing in-tree reads KVPoolRequest today, which is exactly why layout and size could be wrong unnoticed. Dogfooding makes drift impossible by construction and lets a vendor delegate (pool = build_in_tree_kv_pool(req); return MyWrapper(pool)) instead of re-deriving things like enable_alt_stream=not get_disagg().enable_pdmux. It is also the step that makes RFC [Feature] Introduce hardware plugin system #20372's end state mechanical: in-tree platforms become real implementors, Optional goes away, and is_out_of_tree() leaves the configurator.
2. SWA leaf injection — give SWAKVPool full_kv_pool=/swa_kv_pool= parameters and issue two leaf requests, the way HybridLinearKVPool already works in this PR. Principle: vendors build leaves, core builds composites.
3. Narrow the consumption surface — migrate isinstance gates to BaseSWAKVPool/protocols; drop NPUMLATokenToKVPool from disaggregation/utils.py.
4. A conformance kit vendors can run in their own CI, driving _make_kv_pool_request over a model matrix and asserting against real in-tree pool attributes. That is the test that would have caught both review bugs mechanically.

Deliberate non-changes

• Kept the frozen scalar struct rather than a live view object — a copy is right at a plugin boundary; dogfooding, not aliasing, is what stops it drifting.
• Did not split into a tagged union (MHAPoolRequest | MLAPoolRequest | ...). Literal + explicit quant_scheme gets most of the value at a fraction of the diff. Worth doing while there is still exactly one consumer, if reviewers prefer it.
• require_out_of_tree_impl's message is over-broad for get_paged_allocator_cls: PagedTokenToKVPoolAllocator is pure index arithmetic, so a vendor can legitimately return it. Kept for consistency with pre-PR behavior; happy to soften.

[yeahdongcn]

MUSA changes look good to me. Thanks!

[AgainstEntropy]

/rerun-failed-ci