2b.0: adopt l2_pooling pooled-L2 mechanics (default-off)

Adopt the ownerless shared-physical-L2 mechanics from origin/l2_pooling onto the Phase-1 branch, behind --enable-cp-shared-physical-l2-hicache (default off -> behavior-neutral). Foundation for the B1 collective-free allocator (2b.1/2b.2) and the L3 durable floor (Phase 3); no coordination yet.

- cp_shared_l2_pool.py (new): CpSharedL2PageAllocator (deterministic first-fit, capacity charged once, no x cp_size), hugetlbfs-2M slab primitives, position-indexed object ranges, commit-quorum data model.
- memory_pool_host.py: SharedHostTensor* slab orchestration (3-way merged; fix-output's net change to this file is blank-line-only -> additions-only, no content lost).
- server_args.py: flags + _handle_cp_shared_physical_l2_hicache_validation (3-way merged clean with Phase-1 assert + fix-output EnvField).
- test_cp_shared_l2_pool.py: 75 unit tests (allocator/slab/quorum), green on g0033 syh-dev-new; envs stub provides SGLANG_REQ_WAITING_TIMEOUT (read by Phase-1 validation).

Design + B1 proof: docs_internal/cp_hicache_2b_pooled_l2_b1_design.md (sec 2.4).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/sglang/srt/server_args.py

@@ -593,6 +593,10 @@ class ServerArgs:
     hicache_storage_backend: Optional[str] = None
     hicache_storage_prefetch_policy: str = "best_effort"
     hicache_storage_backend_extra_config: Optional[str] = None
+    enable_cp_shared_physical_l2_hicache: bool = False
+    cp_shared_l2_hugetlbfs_dir: str = "/mnt/huge_2m"
+    cp_shared_l2_slab_size_gb: int = 0
+    cp_shared_l2_numa_policy: str = "interleave_2m"
 
     # Hierarchical sparse attention
     enable_hisparse: bool = False
@@ -788,7 +792,9 @@ class ServerArgs:
         # hf_config through get_model_config().
         self._handle_nsa_index_model_override_args()
 
-        # Validate CP shared KV constraints early (before dummy-model short-circuit).
+        # Validate CP shared physical L2 constraints before the broader CP shared KV
+        # checks so users get the most actionable error for the experimental flag.
+        self._handle_cp_shared_physical_l2_hicache_validation()
         self._handle_cp_shared_kv_validation()
 
         # Normalize load balancing defaults early (before dummy-model short-circuit).
@@ -1080,6 +1086,51 @@ class ServerArgs:
             "layer_page_first is supported only with the direct IO backend."
         )
 
+    def _handle_cp_shared_physical_l2_hicache_validation(self):
+        if self.cp_shared_l2_slab_size_gb < 0:
+            raise ValueError("cp_shared_l2_slab_size_gb must be non-negative")
+        if not self.enable_cp_shared_physical_l2_hicache:
+            return
+
+        valid_numa_policies = {
+            "interleave_2m",
+            "balanced_local_preferred",
+            "strict_local",
+            "round_robin",
+        }
+        if self.cp_shared_l2_numa_policy not in valid_numa_policies:
+            raise ValueError(
+                "cp_shared_l2_numa_policy must be one of "
+                f"{sorted(valid_numa_policies)}; got {self.cp_shared_l2_numa_policy!r}"
+            )
+
+        if not self.enable_nsa_prefill_cp_shared_kv:
+            raise ValueError(
+                "--enable-cp-shared-physical-l2-hicache requires "
+                "--enable-nsa-prefill-cp-shared-kv."
+            )
+        if not self.enable_hierarchical_cache:
+            raise ValueError(
+                "--enable-cp-shared-physical-l2-hicache requires "
+                "--enable-hierarchical-cache."
+            )
+        if self.hicache_io_backend != "direct":
+            raise ValueError(
+                "--enable-cp-shared-physical-l2-hicache requires "
+                "--hicache-io-backend direct."
+            )
+        if self.hicache_mem_layout != "layer_page_first":
+            raise ValueError(
+                "--enable-cp-shared-physical-l2-hicache requires "
+                "--hicache-mem-layout layer_page_first."
+            )
+        if self.hicache_storage_backend is not None:
+            raise ValueError(
+                "--enable-cp-shared-physical-l2-hicache does not support "
+                "--hicache-storage-backend; layer_page_first page-buffer "
+                "metadata is not a storage contract."
+            )
+
     def _handle_deprecated_args(self):
         # Handle deprecated tool call parsers
         deprecated_tool_call_parsers = {"qwen25": "qwen", "glm45": "glm"}
@@ -5501,6 +5552,46 @@ class ServerArgs:
             default=ServerArgs.hicache_storage_backend_extra_config,
             help="A dictionary in JSON string format, or a string starting with a leading '@' and a config file in JSON/YAML/TOML format, containing extra configuration for the storage backend.",
         )
+        parser.add_argument(
+            "--enable-cp-shared-physical-l2-hicache",
+            action="store_true",
+            default=ServerArgs.enable_cp_shared_physical_l2_hicache,
+            help=(
+                "Enable experimental ownerless CP shared physical L2 HiCache "
+                "metadata. Requires CP shared KV HiCache with direct "
+                "layer_page_first host layout and no storage backend."
+            ),
+        )
+        parser.add_argument(
+            "--cp-shared-l2-hugetlbfs-dir",
+            type=str,
+            default=ServerArgs.cp_shared_l2_hugetlbfs_dir,
+            help=(
+                "hugetlbfs directory reserved for CP shared physical L2 "
+                "HiCache slabs. The directory is validated by later "
+                "production integration; this flag does not mount or configure "
+                "hugetlbfs."
+            ),
+        )
+        parser.add_argument(
+            "--cp-shared-l2-slab-size-gb",
+            type=int,
+            default=ServerArgs.cp_shared_l2_slab_size_gb,
+            help=(
+                "Physical host tensor slab size in decimal GB for CP shared "
+                "physical L2 HiCache. 0 preserves the legacy single-slab path."
+            ),
+        )
+        parser.add_argument(
+            "--cp-shared-l2-numa-policy",
+            type=str,
+            default=ServerArgs.cp_shared_l2_numa_policy,
+            help=(
+                "Metadata-only NUMA policy for CP shared physical L2 slabs. "
+                "Allowed values: interleave_2m, balanced_local_preferred, "
+                "strict_local, round_robin."
+            ),
+        )
 
         # Hierarchical sparse attention
         parser.add_argument(