Skip to content

Decision record · ADR

ADR-0075: Name KV-transfer mechanisms openly and let each integration validate them

Status: accepted | Date: 2026-11-07

References: RFC-0003, RFC-0006, ADR-0071

A prefill_decode server declares its KV-transfer mechanism in kv_transfer, and the adapter protocol carried it as a closed enumeration of mooncake and nixl. The control plane uses the name to choose a built-in proxy for vLLM, SGLang, and TensorRT-LLM and to require the transport links those mechanisms need, and each framework integration accepts its own subset. The Specialized Engine integration passes the declared mechanism to its Engine as --disaggregation-transfer-backend, and the Engine rejects a mechanism it does not implement before it reports SERVING. One Specialized Engine moves KV pages with its own RDMA transport and accepts only its own mechanism name, which the closed enumeration cannot express; declaring mooncake would pass planning only for the Engine to refuse it, and accepting mooncake as an alias would make records name a mechanism the Engine does not use.

kv_transfer is a mechanism name: a non-empty string of lowercase ASCII letters, digits, -, and _, rejected in any other spelling when the workspace loads. Protocol version 16 carries it as that name in requests and in role links. Each integration validates the names it accepts and rejects any other during resolution before launching a process, so vLLM, SGLang, TensorRT-LLM, TokenSpeed, and Dynamo keep exactly their current sets. The Specialized Engine integration accepts any name and passes it unchanged, because its Engine owns the transport and the contract already requires the Engine to reject one it does not implement. The control plane keeps its mechanism-specific rules for the names it knows — built-in proxy selection and the bootstrap and side-channel links of Mooncake and NIXL — and for any other name accepts the transport links the integration declares, which it still validates structurally. The declared name is recorded unchanged.

An Engine with its own transport runs prefill/decode under its true mechanism name, and records state it. Existing workspaces are unaffected. A misspelled name is no longer caught when the workspace is parsed, only when its integration plans, still before any process launches; the Specialized Engine catches it only when the Engine refuses the name before SERVING, after launch. The wire change is a protocol bump to version 16 with a new Adapter SDK, so every integration package is released with it. The control plane no longer knows the full set of mechanisms in use; anything that keys behavior on a mechanism must handle names it does not know.

Carry the KV-transfer mechanism as a name each integration validates (accepted)

Section titled “Carry the KV-transfer mechanism as a name each integration validates (accepted)”
  • Pros: The record names the transport the Engine actually uses, Existing workspaces keep their mooncake and nixl declarations unchanged
  • Cons: A misspelled name is caught at integration planning, not at workspace parsing

Add a fixed engine value meaning the Engine owns the transport (rejected)

Section titled “Add a fixed engine value meaning the Engine owns the transport (rejected)”
  • Cons: The record says engine while the real transport name lives elsewhere

Treat the Specialized Engine’s transport as an Engine argument with no declared mechanism (rejected)

Section titled “Treat the Specialized Engine’s transport as an Engine argument with no declared mechanism (rejected)”
  • Cons: Requires dropping the mechanism from the prefill/decode link graph and the independent-recording rule, and breaks the qualified DeepInfer 1P1D shape that relies on the rendered mooncake value

Let the Engine accept mooncake as an alias for its own transport (rejected)

Section titled “Let the Engine accept mooncake as an alias for its own transport (rejected)”
  • Cons: Records would name a mechanism the Engine does not use