Expand prefill CP KV capacity by sharding persistent NSA KV

Prefill CP previously replicated NSA/MLA persistent KV on every CP rank, so CP8 consumed eight copies of KV memory while exposing only one rank of logical cache capacity. This change splits logical KV locs from per-rank physical storage, shards MLA latent KV and NSA index K/scale by deterministic page ownership, and keeps existing NSA attention kernels working through a full-view runtime materialization layer.

Mooncake PD transfer now sends each prefill CP rank's owned physical pages with explicit logical page positions so non-CP decode can reconstruct full-layout KV. The implementation is guarded by an explicit server flag and startup checks, and the design documentation records the implemented scope, debug environment, and Phase 3 boundary.

Constraint: Phase 2 must preserve existing NSA attention/index kernels via runtime full-view materialization
Constraint: Decode side remains non-CP and receives full KV through Mooncake
Rejected: Shard-aware NSA attention in this change | belongs to Phase 3 because it requires distributed topk/softmax/output contracts
Rejected: Request-contiguous CP ownership | unstable under chunked prefill and tied to attention split mode
Confidence: medium
Scope-risk: broad
Directive: Do not enable round-robin CP shared KV without wiring runtime materialization/PD transfer contracts for that split mode
Directive: Keep SGLANG_DEBUG_CP_SHARED_KV disabled for perf measurements; it intentionally enables CUDA-syncing diagnostics
Tested: Remote py_compile for shared-KV touched Python files in g0034 container
Tested: Remote pytest selected cp_shared/shared_kv/nsa suite: 37 passed, 34 deselected
Not-tested: Full GLM5 multi-node throughput/regression run after final doc update
Not-tested: Phase 3 shard-aware runtime, round-robin CP mode, and non-Mooncake PD backends

python/sglang/srt/mem_cache/allocator.py

@@ -517,3 +517,41 @@ class PagedTokenToKVPoolAllocator(BaseTokenToKVPoolAllocator):
 
     def load_cpu_copy(self, kv_cache_cpu, indices):
         return self._kvcache.load_cpu_copy(kv_cache_cpu, indices)
+
+
+class CPSharedPagedTokenToKVPoolAllocator(PagedTokenToKVPoolAllocator):
+    """Paged allocator that returns CP-group logical KV locations.
+
+    The allocator tracks logical pages visible to scheduler/radix/req_to_token.
+    The physical KV pool is smaller; logical-to-physical translation happens at
+    actual KV buffer access time through CpSharedKVLayout.
+    """
+
+    def __init__(
+        self,
+        logical_size: int,
+        physical_size: int,
+        page_size: int,
+        dtype: torch.dtype,
+        device: str,
+        kvcache: KVCache,
+        need_sort: bool,
+        cp_size: int,
+        cp_rank: int,
+    ):
+        if logical_size % page_size != 0:
+            raise ValueError("logical_size must be page aligned")
+        if physical_size % page_size != 0:
+            raise ValueError("physical_size must be page aligned")
+        if logical_size != physical_size * cp_size:
+            raise ValueError(
+                "logical_size must equal physical_size * cp_size, got "
+                f"{logical_size=} {physical_size=} {cp_size=}"
+            )
+        if not 0 <= cp_rank < cp_size:
+            raise ValueError(f"cp_rank must be in [0, {cp_size}), got {cp_rank}")
+
+        super().__init__(logical_size, page_size, dtype, device, kvcache, need_sort)
+        self.physical_size = physical_size
+        self.cp_size = cp_size
+        self.cp_rank = cp_rank